<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
    <meta http-equiv="Content-Language" content="EN-US">
    <meta name = "format-detection" content = "telephone=no">
    <style type="text/css">
body { font: 12px "lucida grande", geneva, helvetica, arial, sans-serif; color: #000; background-color: #FFF; }
h1   { margin-top: 1.0em; margin-bottom: 0.8334em; font-size: 2.5000em; }
h2   { margin-top: 2.5em; margin-bottom: 2.0000ex; font-size: 2.0000em; border-bottom: 1px solid #5088C5; color: #3C4C6C; clear: both; }
h3   { margin-top: 2.0em; margin-bottom: 0.5000em; font-size: 1.5834em; }
h4   { margin-top: 2.0em; margin-bottom: 0.5000em; font-size: 1.2500em; }
h5   { margin-top: 1.5em; margin-bottom: 0.5000em; font-size: 1.0834em; padding: 0px; }

A:link, a:link .code          { text-decoration: none;      color: #36C; }
A:link:hover, a:link:hover .code    { text-decoration: underline; color: #36C; }
A:active, a:active .code        { text-decoration: underline; color: #36C; }
A[name]:active                { text-decoration: none;      color: #000; }
A:visited, a:visited .code       { text-decoration: none;      color: #036; }
A:visited:hover, a:visited:hover .code { text-decoration: underline; color: #036; }

.spacer { height: 0px; width: 100%; margin-top: 0.5em; margin-bottom: 0.5em; border-top: 1px solid #fafafa; border-bottom: 1px solid #fdfdfd; }
.indent  { margin-left: 4ex; }
.bar { height: 0px; width: 100%; margin-top: 0.5em; margin-bottom: 0.5em; border-bottom: 1px solid #a1a5a9; }

.hide { display: none; }

.RED { border: 2px solid #f00; padding: 1ex; -webkit-border-radius: 5px; -webkit-box-shadow: 3px 3px 4px #900; -moz-border-radius: 5px; -moz-box-shadow: 3px 3px 4px #900; border-radius: 5px; box-shadow: 3px 3px 4px #900; white-space: pre-wrap; }
.XXX { border: 2px solid red; padding: 2px; margin: 0.75em 0px; }
.XXX { border-color: rgba(255,0,0,0.8); -webkit-border-radius: 6px; /*text-shadow: 2px 2px 2px rgba(68,0,0,0.4);*/ -moz-border-radius: 6px; border-radius: 6px; }

.DoNot { font-weight: bold; font-style: italic; text-decoration: underline; }

.nobr        { white-space: nowrap; white-space: pre-wrap !important; }
.hardNobr    { white-space: nowrap; }
.noBold      { font-weight: normal !important; }
.noUnderline { text-decoration: none !important; }

img.noBorder { border: 0px solid #000; }

.noSelect { -moz-user-select: none; -webkit-user-select: none; cursor: default; }
.canSelect { -moz-user-select: text; -webkit-user-select: text; cursor: auto; }

.marginTopSpacer    { margin-top:    1em !important; }
.marginBottomSpacer { margin-bottom: 1em !important; }
.marginLeftSpacer   { margin-left:   1ex !important; }
.marginRightSpacer  { margin-right:  1ex !important; }
.marginSpacer       { margin:        1em 1ex !important; }

.floatRight       { float: right; }
.floatRightPadder { text-align: right; clear: both; height: 0px; }
.floatLeft        { float: left; }
.floatLeftPadder  { text-align: left; clear: both; height: 0px; }

.clearLeft  { clear: left;  }
.clearRight { clear: right; }
.clearBoth  { clear: both;  }

.rightHack { text-align: right; text-align: -webkit-right; text-align: -moz-right; }
.centerHack { text-align: center; text-align: -webkit-center; text-align: -moz-center; }
.leftHack { text-align: left; text-align: -webkit-left; text-align: -moz-left; }

.submenuArrow { font-size: 0.75em; }

.table { display: table; }
.table > .row { display: table-row; }
.table > .row > .cell { display: table-cell; }

.table > .row > .cell.metacharacters { width: 50%; }
.table > .row > .cell.operators { width: 50%; }

.table.perfNumbers > .row > .cell { padding-right: 1.5em; }

ul.highlights    { margin-left: 4.0ex; padding-left: 1ex; }
ul.highlights li { margin-top: 0.5em; }

ul.square  { list-style-type: square; }
ul.square > li > *:first-child { margin-top: 0px; }
ul.square > li > .box.sourcecode:last-child { margin-bottom: 1em; }

ul.compare { margin: 0px; padding: 0px; }
ul.compare > li { margin: 0px 0px 0px 2ex; }

ul.overview    { margin-left: 9.5ex; list-style-type: none; }
ul.overview li { margin-top: 0em; }

ul.seealso { margin: 0px; padding: 0px; list-style-type: none; }
ul.seealso > li { margin: 0px 0px 0px 6.25ex; }

/* table styles */

table + table { margin-top: 1em; }
table + .box { margin-top: 1em; }

/* The standard table style */
table.standard                       { border-spacing: 0px; -moz-border-radius: 0.5ex; -webkit-border-radius: 0.5ex; border-radius: 0.5ex; }
table.standard caption               { margin-bottom: 0.5em; text-align: left; }
table.standard caption > .identifier { font-weight: bold; margin-right: 1.5ex; }
table.standard th                    { padding: 0.3334em 1ex; text-align: left;  border-bottom: 1px solid #919699; border-right: 1px solid #919699; background: #E2E2E2; }
table.standard td                    { vertical-align: top; padding: 1ex; border-bottom: 1px solid #919699; border-right: 1px solid #919699; }


table.standard tr:first-child > *:first-child, table.regexSyntax tr:first-child > *:first-child { -moz-border-radius-topleft:     0.5ex; -webkit-border-top-left-radius:     0.5ex; border-top-left-radius:     0.5ex; }
table.standard tr:first-child > *:last-child,  table.regexSyntax tr:first-child > *:last-child  { -moz-border-radius-topright:    0.5ex; -webkit-border-top-right-radius:    0.5ex; border-top-right-radius:    0.5ex; }
table.standard tr:last-child  > *:first-child, table.regexSyntax tr:last-child  > *:first-child { -moz-border-radius-bottomleft:  0.5ex; -webkit-border-bottom-left-radius:  0.5ex; border-bottom-left-radius:  0.5ex; }
table.standard tr:last-child  > *:last-child,  table.regexSyntax tr:last-child  > *:last-child  { -moz-border-radius-bottomright: 0.5ex; -webkit-border-bottom-right-radius: 0.5ex; border-bottom-right-radius: 0.5ex; }

table.regexSyntax                       { border-spacing: 0px; /* border-top: 1px solid #919699; border-left: 1px solid #919699; */ margin-left: 1.5ex; margin-right: 1.5ex; -moz-border-radius: 0.5ex; -webkit-border-radius: 0.5ex; border-radius: 0.5ex; }
table.regexSyntax caption               { margin-bottom: 0.5em; text-align: left; }
table.regexSyntax caption > .identifier { font-weight: bold; margin-right: 1.5ex; }
table.regexSyntax th                    { padding: 0.3334em 1ex; text-align: left;  border-bottom: 1px solid #919699; border-right: 1px solid #919699; background: #E2E2E2; -webkit-background-origin: border; }
table.regexSyntax td                    { padding-left: 0.75ex; padding-right: 0.75ex; padding-top: 0.1875em; padding-bottom: 0.1875em; border-bottom: 1px solid #919699; border-right: 1px solid #919699; -webkit-background-origin: border; }

table.regexSyntax i + .regex { margin-left: 0.3125ex; }

.redOutline      { outline: 1px solid rgba(255,0,0,0.25); }
.greenOutline    { outline: 1px solid rgba(0,255,0,0.25); }
.blueOutline     { outline: 1px solid rgba(0,0,255,0.25); }

.transitionColor { -webkit-transition: color 0.33s cubic-bezier(0.43, 0, 1.0, 0.75), text-shadow 0.33s cubic-bezier(0.43, 0, 1.0, 0.75); }
.transitionRed   { color: #f00 !important; }
.transitionGreen { color: #0f0 !important; text-shadow: 1px 1px 3px rgba(0,255,0,0.4); }
.transitionBlue  { color: #00f !important; }

.pulseOutlineRed { -moz-box-shadow: 0px 0px 1.85ex rgba(255,0,0,1.0) !important; -webkit-box-shadow: 0px 0px 1.85ex rgba(255,0,0,1.0) !important; }
.pulseOutline { -webkit-transition: -webkit-box-shadow 0.5s ease-out; }

.copyToClipboardHUDAnimate { -webkit-transition: top 0.25s ease-in-out, width 0.45s ease-in-out, left 0.45s ease-in-out; }

.copyToClipboardHUD { -moz-user-select: none; -webkit-user-select: none; cursor: default; }
.copyToClipboardHUD > .top { padding-top: 0px; padding-bottom: 0px; margin-left: 35px; margin-right: 35px; background: rgba(8,8,8,0.75); -webkit-border-bottom-left-radius: 10px; -webkit-border-bottom-right-radius: 10px; border-bottom-left-radius: 10px; border-bottom-right-radius: 10px; -moz-border-radius-bottomleft: 10px; -moz-border-radius-bottomright: 10px;  border: 2px solid rgb(207,207,207); border-top: 0px solid transparent; -moz-box-shadow: 0px 0px 10px rgba(0,0,0,0.9); color: #fff; text-shadow: 0px 0px 1px rgba(0,0,0,0.75); -webkit-box-shadow: 0px 0px 10px rgba(0,0,0,0.9); box-shadow: 0px 0px 10px rgba(0,0,0,0.9); z-index: 100; text-align: center; -webkit-background-origin: border !important; -moz-background-origin: border; }
.copyToClipboardHUD > .top > .padding { padding-top: 0.25em; padding-bottom: 0.5em; }
.copyToClipboardHUD > .top > .padding > .copiedAs { white-space: nowrap; margin-left: 3ex; margin-right: 3ex; font-weight: bold; }
.copyToClipboardHUD .copyToClipboardHUDRegex { margin-top: 0.75em; margin-left: 4ex; margin-right: 4ex;  color: #fff; text-shadow: 0px 0px 2px rgba(0,0,0,0.75); overflow: hidden; text-overflow: ellipsis; -webkit-background-origin: border; -moz-background-origin: border; }
.copyToClipboardHUD.example > .top { margin-right: 13px; margin-left: 13px; }

.copyToClipboardDisplayExample { margin: 1em 0px; }
.copyToClipboardDisplayExample .cell { vertical-align: top; }

div.clipboardExamples#topContainer { margin-bottom: 0.5em; }
div#clip { overflow: hidden; }

.faq { margin-left: 6ex; margin-right: 6ex; }
.faq > .qa { margin-bottom: 1.5em;  }
.faq > .qa > .q { font-weight: bold; }
.faq > .qa > .a { margin: 0.25em 1.75ex; }
.faq > .qa > .q > p:first-child, .faq > .qa > .a > p:first-child { margin-top: 0px; }

.bottomBevel { border-bottom: 1px solid #e0e0e0; border-bottom: 1px solid rgba(0,0,0,0.1); -webkit-background-origin: border; -moz-background-origin: border; }
.topBevel    { border-top: 1px    solid #fdfdfd; border-top:    1px solid rgba(255,255,255,0.75); -webkit-background-origin: border; -moz-background-origin: border; }
.leftBevel   { border-left: 1px   solid #fdfdfd; border-left:   1px solid rgba(255,255,255,0.75); -webkit-background-origin: border; -moz-background-origin: border; }
.rightBevel  { border-right: 1px  solid #e0e0e0; border-right:  1px solid rgba(0,0,0,0.1); -webkit-background-origin: border; -moz-background-origin: border; }

.box   { margin: 0.5em 3ex; padding: 0.5em 1.75ex; text-align: left; vertical-align: top; border: 1px solid #a1a5a9; background-color: #f7f7f7; }
.box + .box { margin-top: 1em; }
.box p { margin: 0px 0px; }
.box p + p { margin-top: 1em; }

.box.important       { border-color: #111; background-color: #e8e8e8; }
.box.warning         { border-color: #000; background-color: #fff;    }
.box.caution         { border-color: #000; background-color: #fcfcfc; border-width: 2px; }
.box.tip, .box.small { border-color: #c3c3c3; background-color: #e9e9e9; padding: 0.25em 1.0ex; }

.box.tip   { display: table; -webkit-border-radius: 1.0em; -moz-border-radius: 1.0em; border-radius: 1.0em; }
.box.small { float: left; clear: both; margin: 0.5ex; -webkit-border-radius: 0.85em; -moz-border-radius: 0.85em; border-radius: 0.85em; }
.box.note, .box.important, .box.warning, .box.caution { -webkit-border-radius: 0.5em; -moz-border-radius: 0.5em; border-radius: 0.5em; color: #000; }
.box .message p:first-child { margin-top: 0px; }
.box .message p:last-child { margin-bottom: 0px; }

.box       .label { padding-right: 1.5ex; font-weight: bold; vertical-align: middle; }
.box.tip   .label { padding-right: 1.0ex; }
.box.small .label { padding-right: 0.5ex; }

.box.sourcecode, .box.shell, .box.quote { margin-left: 0px; margin-right: 0px; padding: 1.0em 2ex; -webkit-border-radius: 0.5ex; -moz-border-radius: 0.5ex; border-radius: 0.5ex; }
.box.sourcecode, .box.shell, .shellFont { font: 0.9167em monaco, "Lucida Console", courier, monospace; }
.box.sourcecode, .box.shell { white-space: pre; white-space: pre-wrap !important; }
.box.sourcecode { border: 1px solid #c7cfd5; background-color: #f1f5f9; }
/*.box.sourcecode .comment        { font-weight: bold;   font-size: 0.9167em; }*/
.box.shell      { border: 1px solid #bddbc5; background-color: #eafff5; }
.box.quote      { border: 1px solid #c7cfd5; background-color: #f0f0f0; }
.box.shell .userInput         { font-weight: bold;   font-size: 0.9167em; }
.box.shell .userInput .return { font-weight: normal; font-size: 1.1000em; margin-left: 0.5ex; }

.box.hasRows                                 { display: table; padding: 0px; background-color: white; border-left: 1px solid #919699; border-top: 1px solid #919699; }
.box.hasRows > .row                          { display: table-row;  }
.box.hasRows > .row         > .cell          { display: table-cell; padding: 1ex; border-bottom: 1px solid #919699; border-right: 0.834em solid #919699; }
.box.hasRows > .row         > .cell.lastCell { border-right: none;  }
.box.hasRows > .row.lastRow > .cell          { border-bottom: none; }

/* zebra rows are tagged even/odd.  Scripts/common.js:fixupBoxRows() will automatically populate and/or correct any even/odd tags */
.box.hasRows.zebraRows > .row.odd             { background-color: #F0F5F9;                       }
.box.hasRows           > .row.headerRow       { background-color: #E2E2E2;                       }
.box.hasRows           > .row.headerRow .cell { padding-top: 0.3334em; padding-bottom: 0.3334em; }

.box.frameworkSpecs .row.regexKitVersion .releaseNotes, .box.classSpecs .row.regexKitVersion .releaseNotes { margin-left: 2ex; }
.box.classSpecs > .row > .cell.left { font-weight: bold; border-right: none; }
.box.classSpecs > .row > ul.cell.right { list-style-type: none; }

.box.classSpecs { -webkit-border-radius: 0.5ex; -moz-border-radius: 0.5ex; border-radius: 0.5ex; }

.box.hasRows > .row:first-child  { -moz-border-radius-topleft:     0.5ex; -webkit-border-top-left-radius:     0.5ex; border-top-left-radius:     0.5ex; -moz-border-radius-topright:    0.5ex; -webkit-border-top-right-radius:    0.5ex; border-top-right-radius:    0.5ex; }
.box.hasRows > .row:last-child   { -moz-border-radius-bottomleft:  0.5ex; -webkit-border-bottom-left-radius:  0.5ex; border-bottom-left-radius:  0.5ex; -moz-border-radius-bottomright: 0.5ex; -webkit-border-bottom-right-radius: 0.5ex; border-bottom-right-radius: 0.5ex; }

.box.hasRows > .row:first-child > *:first-child { -moz-border-radius-topleft:     0.5ex; -webkit-border-top-left-radius:     0.5ex; border-top-left-radius:     0.5ex; }
.box.hasRows > .row:first-child > *:last-child  { -moz-border-radius-topright:    0.5ex; -webkit-border-top-right-radius:    0.5ex; border-top-right-radius:    0.5ex; }
.box.hasRows > .row:last-child  > *:first-child { -moz-border-radius-bottomleft:  0.5ex; -webkit-border-bottom-left-radius:  0.5ex; border-bottom-left-radius:  0.5ex; }
.box.hasRows > .row:last-child  > *:last-child  { -moz-border-radius-bottomright: 0.5ex; -webkit-border-bottom-right-radius: 0.5ex; border-bottom-right-radius: 0.5ex; }


.box .highlight { padding-left: 0.175ex; padding-right:0.175ex; padding-bottom: 0.1em; margin-right:0.175ex; margin-left:0.175ex; border: 1px solid #888; -webkit-border-radius: 0.5em; -moz-border-radius: 0.5em; border-radius: 0.5em;  }

.box .metainfo { display: table; font: 12px "lucida grande", geneva, helvetica, arial, sans-serif; white-space: normal; padding: 0.125em 0.75ex; border: 1px solid #ccc; border-color: rgba(0,0,0,0.15); background-color: rgba(0,0,0,0.05); -webkit-border-radius: 0.5em; -moz-border-radius: 0.5em; border-radius: 0.5em; float: right; -webkit-user-select: none; -moz-user-select: none; cursor: default; -webkit-background-origin: border; -moz-background-origin: border; }
.box .metainfo .info { padding-left: 1.0ex; }
.box .metainfo > .entry { display: table-row; }
.box .metainfo > .entry > .item { display: table-cell; }
.box .metainfo > .entry > .meta { font-style: italic; }

.box .metainfo .filename > .info, .box .metainfo .taggedAs > .info { font: 0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.box .metainfo .continues.above > .info { padding-left: 0px; font: italic 0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.box .metainfo .description > .info { padding-left: 0px; font: italic 0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }

.box.titled           { margin: 0px; padding: 0px; border: 0px solid transparent; background-color: transparent; -webkit-border-radius: 0.625em; -moz-border-radius: 0.625em; border-radius: 0.625em; }
.box.titled > .title    { padding: 0.25em 2ex; line-height: 1.5em; font-size: 13px; font-weight: bold; -webkit-border-top-left-radius: 0.625em; -webkit-border-top-right-radius: 0.625em; border-top-left-radius: 0.625em; border-top-right-radius: 0.625em; -moz-border-radius-topleft: 0.625em; -moz-border-radius-topright: 0.625em; -webkit-user-select: none; -moz-user-select: none; cursor: default; -webkit-background-origin: border; -moz-background-origin: border; background-origin: border; }
.box.titled > .contents { padding: 0.5em 2ex; line-height: 1.5em; font-size: 11px; -webkit-border-bottom-left-radius: 0.625em; -webkit-border-bottom-right-radius: 0.625em; border-bottom-left-radius: 0.625em; border-bottom-right-radius: 0.625em; -moz-border-radius-bottomleft: 0.625em; -moz-border-radius-bottomright: 0.625em; border: 1px solid #e5e5e5; border-top: 0px !important; background: #f5f5f5; color: #555; -webkit-background-origin: border; -moz-background-origin: border; background-origin: border; }

.box.titled > .title.blueGrey { background: #7a88a1; background: -webkit-gradient(linear, left top, left bottom, from(rgba(162,170,186,1.0)), to(rgba(114,131,157,1.0))); background: -moz-linear-gradient(top, rgba(162,170,186,1.0), rgba(114,131,157,1.0)); color: #fff; text-shadow: 0px 1px 2px #333;
border-top: 1px solid rgba(255,255,255,0.125); border-left: 1px solid rgba(0,0,0,0.025); border-right: 1px solid rgba(0,0,0,0.025); border-bottom: 1px solid rgba(0,0,0,0.025); -webkit-background-origin: border !important;
}

.box.titled > .title.dkRed  { background: #7c2f26; background: -webkit-gradient(linear, left top, left bottom, from(rgba(140,96,91,1.0)), color-stop(0.0125, rgba(145,100,94,1)), color-stop(0.66,rgba(117,43,35,1.0)), to(rgba(115,42,34,1.0))); color: #fff; text-shadow: 0px 1px 2px #222; }

.box.titled > .title.metal { background: #d8d8d8; background: -webkit-gradient(linear, left top, left bottom, from(rgba(223,223,223,1.0)), to(rgba(206,206,206,1.0)) ); color: #666; text-shadow: 1px 1px 0px #e9e9e9; text-shadow: 1px 1px 0px rgba(255,255,255,0.4); border-top: 1px solid rgba(255,255,255,0.65); border-left: 1px solid rgba(0,0,0,0.04); border-right: 1px solid rgba(0,0,0,0.04); border-bottom: 1px solid #afafaf; }
.box.titled > .contents.metal { background: #ccc; background: -webkit-gradient(linear, left top, left bottom, from(rgba(204,204,204,1.0)), to(rgba(190,190,190,1.0))); color: #fff; text-shadow: 0px 1px 2px #333; border-top: 1px solid #e0e0e0 !important; border-left: 1px solid rgba(0,0,0,0.04); border-right: 1px solid rgba(0,0,0,0.04); border-bottom: 1px solid #aaa; }

.box.titled > .title.alum { background: #eee; color: #333; border: 1px solid #d3d3d3; border-bottom: 1px solid #bcbcbc !important; }
.box.titled > .contents.alum { background: #fafafa; color: #555; border-top-width: 0px; border-left: 1px solid #e1e1e1; border-right: 1px solid #e1e1e1; border-bottom: 1px solid #c4c4c4; }

.box.titled > .contents.alum2 { color: #222; background: #f8f8f8; border-top: 1px solid #fcfcfc !important; border-left: 1px solid #e1e1e1; border-right: 1px solid #e1e1e1; border-bottom: 1px solid #c4c4c4; }

.box.titled > .contents.whiteToLight { background: -webkit-gradient(linear, left top, left bottom, from(rgba(255,255,255,1.0)), to(rgba(241,241,241,1.0))); border: 1px solid #cecece; }

.box.titled > .contents.whiteToLight2 { background: -webkit-gradient(linear, left top, left bottom, from(rgba(250,250,250,1.0)), to(rgba(241,241,241,1.0))); border: 1px solid #cecece; }

.box.titled.copyToClipboard.preferences { float: right; margin: 1em 3ex; -moz-user-select: none; -webkit-user-select: none; max-width: 33%; min-width: 350px; cursor: default; }

.box.titled.copyToClipboard.preferences .contents .inset .code { color: #222; }

.box.titled.copyToClipboard.preferences .contents .inset .prefsUI { margin: 3px; }

.box.titled.copyToClipboard.preferences .contents .inset .prefsUI .copyRegexPrefsRow > .UIlabel { text-align: right; }
.box.titled.copyToClipboard.preferences .contents .inset .prefsUI .copyRegexPrefsRow > .UIcontrol, .box.titled.copyToClipboard.preferences .contents .inset .prefsUI .copyRegexPrefsRow > .UIcontrolLabel { text-align: left; }

.box.titled.copyToClipboard.preferences .contents .inset .prefsUI input { margin: 0px; }

.box.titled.regexEscapeTool.UIpane { width: 45%; max-width: 75%; min-width: 350px; float: right; margin: 2em 3ex; }
.box.titled.regexEscapeTool.UIpane .contents .contain { position: relative; padding-right: 4px; }
.box.titled.regexEscapeTool.UIpane textarea.regex { width: 100%; resize: none; -webkit-border-radius: 3px; border-color: #c4c4c4; border-top-color: #aaa; padding: 1px; font-size: 1em; }

.box.titled.regexEscapeTool.UIpane .inset { font-size: 12px; }
.box.titled.regexEscapeTool.UIpane .inset #interactiveEscapedOutput { min-height: 5em; max-height: 12em; margin: 0.125em 1.0ex; white-space: pre-wrap; overflow: auto; text-shadow: 1px 1px 1px rgba(0,0,0,0.2); color: #333;  }

.safariOnly { display: none; }
.enhancedCopyOnly { display: none; }
.disabledPref, .disabledPref > *, .disabledPref > * > *, .disabledPref > * > * > * { color: #808080 !important; }

.copyToClipboard.preferences .hidden { opacity: 0; }

.copyToClipboard.preferences .marginAndOpacityTransition        { -webkit-transition: margin-bottom 0.25s ease-out,    opacity 0.15s ease-out; -webkit-transition-delay: 1s; }
.copyToClipboard.preferences .marginAndOpacityTransition.hidden { -webkit-transition: margin-bottom 0.25s ease-in-out, opacity 0.15s ease-out; -webkit-transition-delay: 1s;}

.UIcontrolLabel { cursor: default; }

.clipboardExamples .UIlabel { margin: 0.5em 0px 0.25em 0.25ex }

.copyToClipboard.preferences .contents .UItopTitleSpacer { margin-top: 6px; }
.box.titled .contents .UIcontentSpacer { margin: 6px 0px 4px 0px; }

.prefWarnings .prefWarningsSpacer { margin: 0.25em 1ex; }
.prefWarnings .prefWarningsTable + .prefWarningsTable { margin-top: 0.5em; }
.prefWarnings .prefWarningsTable > .row > .cell.label { text-align: right; padding-right: 1.5ex; }

.escapedUnicodeInNSStringLiterals { display: inline; }

hr.beveled { margin: 0px; border: 0px solid transparent; border-top: 1px solid rgba(0,0,0,0.1); border-bottom: 1px solid rgba(255,255,255,0.75); -webkit-background-origin: border; -moz-background-origin: border; }
.copyToClipboard.preferences hr.beveled { margin: 0.125em 0px; }

.insetOuter  { -moz-border-radius: 6px; -webkit-border-radius: 6px; border-radius: 6px; border-top: 1px solid rgba(0,0,0,0.25); -webkit-background-origin: border; -moz-background-origin: border; background-origin: border; }
.insetMiddle { -moz-border-radius: 5px; -webkit-border-radius: 5px; border-radius: 5px; border-top: 1px solid rgba(0,0,0,0.15); border-left: 1px solid rgba(0,0,0,0.14); border-right: 1px solid rgba(0,0,0,0.12); border-bottom: 1px solid rgba(0,0,0,0.10); -webkit-background-origin: border; -moz-background-origin: border; background-origin: border; }
.inset       { -moz-border-radius: 4px; -webkit-border-radius: 4px; border-radius: 4px; border-top: 1px solid rgba(0,0,0,0.05); border-left: 1px solid rgba(0,0,0,0.04); border-right: 1px solid rgba(0,0,0,0.03); border-bottom: 1px solid rgba(0,0,0,0.02); background: #f8f8f8; background: rgba(0,0,0,0.03); -webkit-background-origin: border; -moz-background-origin: border; background-origin: border; }


.figure .caption { margin-bottom: 0.5em; margin-top: 0.5em; }
.figure .caption .number { font-weight: bold; margin-right: 1.25ex; white-space: nowrap; }


.signature { margin-top: 1em; margin-bottom: 0.75em; font: 0.9166em monaco, "Lucida Console", courier, monospace; }
.signature .code { font-size: 1em !important; }

.block { margin: 2.5em 0px 0px 0px; padding: 2.5em 0px 0px 0px; }
.block .header + p { margin-top: 0px; }

.block.dtrace.small > .signature { margin-left: 2ex; }

.section { margin-top: 1em; margin-bottom: 1em; padding: 0px; }
.section > .header { font-weight: bold; font-size: 1.0834em; margin-bottom: 0.1667em; }
.section p { margin-top: 0.5em; margin-bottom: 0.5em; }
.section.discussion p { margin-top: 1em; margin-bottom: 1em; }

.section.summary { margin-top: 0.75em; margin-bottom: 0.75em; }
.section.name { font-size: 1.5833em; font-weight: bold; margin-top: 0px; margin-bottom: 0px; }
.section.parameters { margin-top: 1.5em; }
.section.block.parameters { margin-top: 0.5em; }

.section.seealso ul { list-style-type: none; margin: 0px; padding: 0px; }
.section.seealso li { margin: 0px; }
.section.seealso ul.offset > li, ul.seealso > li { margin: 0px 0px 0px 6.25ex; }

.section.parameters   ul { list-style-type: none; margin: 0px 0px 0px 2ex; padding: 0px; } 
.section.parameters   li { margin: 0px; }
.section.parameters   li  .name { font-style: italic; }
.section.parameters   li  .text { margin-top: 0.0834em; margin-left: 4ex; margin-bottom: 0.5em; }

.block.typedef { margin-top: 5em; margin-bottom: 0px; padding-top: 0px; }
.block.typedef > .section.name { margin-bottom: 0.5em; }
.block.typedef > .section.summary { margin-top: 1em; }
.block.typedef > .section.type { margin-bottom: 0.75em; font: 0.9166em monaco, "Lucida Console", courier, monospace; }

.block.constants { margin-top: 1.5em; padding-top: 0px; }
.block.constants > .section.summary { margin-top: 1em; margin-bottom: 1.25em; }
.block.constants > .section.declaration .code { font-size: 1em; color: #000; }

.block > .section.declaration { font: 0.9167em monaco, "Lucida Console", courier, monospace; color: #000; margin-top: 0px; margin-bottom: 0px; }
.block > .section.declaration > .enum > .identifier { padding-left: 4ex; }
.block > .section.declaration > .enum > .equals {  padding-left: 2ex; padding-right: 2ex; }

.block > .section.constants { margin-top: 1.5em; }
.block > .section.constants > .section.summary { margin-top: 1em; margin-bottom: 1.25em; }
.block > .section.constants > .section.header { margin-bottom: 0.25em; }
.block > .section.constants > .section.declaration .name.code { color: #000; }
.block > .section.constants > .constant  { margin-top: 0.5em; margin-bottom: 0.5em; }
.block > .section.constants > .constant > .identifier { font: 0.9167em monaco, "Lucida Console", courier, monospace; /*color: #666;*/ }
.block > .section.constants > .constant > .text { margin-left: 2ex; }
.block > .section.constants > .constant > .text > p { margin-top: 0px; margin-bottom: 0px; }
.block > .section.constants > .constant > .text > p + p { margin-top: 1em; }

h1.reference { margin-top: 2.5em; }
h3 .code { color: black; }
h4 .code { color: black; }

.overview { margin-bottom: 1em; }
.overview .masthead { font-size: 2.0000em; font-weight: bold; margin-top: 2.5em; margin-bottom: 2.0ex; border-bottom: 1px solid black; }
.overview .header   { font-size: 1.5833em; font-weight: bold; margin-top: 1.5em; margin-bottom: 0.5em; }
.overview .section  { font-size: 1.2500em; font-weight: bold; margin-top: 2.0em; margin-bottom: 0.5em; }
.overview .seealso > ul { margin: 0px; padding: 0px; list-style-type: none; }
.overview .seealso > ul > li { margin-left: 6.25ex; }

.tasks { margin-bottom: 1em; }
.tasks > .header { font-size: /*1.5833em;*/ 1.4166em; font-weight: bold; margin-top: 1.5em; margin-bottom: 0.5em; }
.tasks .header .code { font: bold 1em "lucida grande", geneva, helvetica, arial, sans-serif; }
.tasks > ul { margin: 0px; padding: 0px; list-style-type: none; }
.tasks > ul > li { margin-left: 6.25ex; }

.protocols { margin-bottom: 1em; }
.protocols > .header { margin-bottom: 0.75ex; }
.protocols > ul { margin: 0px; padding: 0px; list-style-type: none; }
.protocols > ul > li { margin-left: 6.25ex; }

.chrono                                         { margin-left: 1.5ex; margin-bottom: 2em; padding-right: 4ex; }
.chrono ul                                      { margin-left: 4.0ex; padding-left: 1ex; list-style-type: square; }
.chrono ul li                                   { margin-top: 0.5em; }
.chrono ul.square > li > *:first-child { margin-top: 0px; }
.chrono ul.square > li > *:last-child { margin-bottom: 0px; }
.chrono ul.square > li > * { margin-top: 0.5em; margin-bottom: 0.5em; }
.chrono ul.square > li > .box.sourcecode { margin-bottom: 0.85em; }
.chrono > .entry                                { margin-left: 2ex; margin-bottom: 1.75em; padding-right: 2ex; }
.chrono > .entry > .banner                      { margin-left: -1.25ex; font-size: 1.0834em; }
.chrono > .entry > .banner > .bannerItemSpacer  { margin-right: 1.25ex; margin-left: 1.25ex; }
.chrono > .entry > .bannerSpacer                { margin-left: -2.0ex; border-bottom: 1px solid #d8d8d8; margin-top: 0.25em; margin-bottom: 0.25em; width: 95% }
.chrono > .entry > .content                     { margin-top: 0.5em; }
.chrono > .entry > .content > p:first-child     { margin-top: 0px; margin-bottom: 0px; }
.chrono > .entry > .content .standout           { margin-top: 1.75em; /*margin-bottom: 0.5000em;*/ font-size: 1.0875em; font-weight: bold; }

.quotation { margin: 1em 6.25ex 1em 6.25ex; }
.quotation .quote { font-style: italic; padding-right: 2.5ex; }
.quotation .attribution { text-align: right; font-variant: small-caps; }
.quotation .attribution:before { content:"\2014"; }

.sourceLicense { margin: 2em 4ex; max-width: 5.75in; text-align: justify; }
.sourceLicense ul { list-style-type: disk; }
.sourceLicense li { margin-bottom: 0.75em; }
.sourceLicense .disclaimer { font-family: courier, monospace; }

.pop-up_menu-selection, .pop-up_menu-name, .menu-selection, .checkbox-name, .tab-name, .button-name, .icon-button-name { font: 0.9167em monaco, "Lucida Console", courier, monospace !important; white-space: nowrap !important; }

.deprecated        { color: #f00; }
.quotedText        {        font:         0.9167em monaco, "Lucida Console", courier, monospace; }
.code              {        font:         0.9167em monaco, "Lucida Console", courier, monospace; /*color: #666;*/ }
.parameterChoice   {  font-style: italic; font-size: 0.9167em; white-space: nowrap; margin-right: 0.2em; }
.consoleText       {        font:         0.8334em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.regex             {        font:         0.8334em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.regex b           {        font: bold    1.1000em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.regex-textual     {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.regex-def         {        font: italic  0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.regexMatch        {        font:         0.8334em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.argument          {  font-style: italic; white-space: nowrap; }
.section-link      {  font-style: italic; white-space: nowrap; white-space: pre-wrap !important; }
.cpp_flag          { font-weight: bold; white-space: nowrap; }
.code .cpp_flag    { font-weight: normal; font-style: italic; white-space: nowrap; }
.cpp_definition    { font-weight: bold; color: #f00; }
.header_file       {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; /*color: #666;*/ }
.frameworkabstract {   font-size:         1.0000em; }
.file              {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; /*color: #666;*/ }
.build-phase       {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.dialog-option     {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.xcode-group       {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.xcode-setting     { font-weight: bold;   white-space: nowrap; }
.xcode-target      {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.window-name       {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.context-menu      {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.xcode-button      {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; }
.user-supplied     {  font-style: italic; white-space: nowrap; }
.new-term          { font-weight: bold;   white-space: nowrap; }
.exponent          {   font-size:         0.7500em; vertical-align: super; } 
.unicodeCharName   {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; /*color: #666;*/ }
.unicodeProperty   {        font:         0.9167em monaco, "Lucida Console", courier, monospace; white-space: nowrap; /*color: #666;*/ }
.standardFont      {        font: 1em "lucida grande", geneva, helvetica, arial, sans-serif; }
.rkl { white-space: nowrap; }


@media screen {
.printOnly { display: none; }

.softNobr    { white-space: nowrap; }

.syntax > .specification .optional { -moz-box-shadow: 2px 3px 5px #888; -webkit-box-shadow: 2px 3px 5px #888; box-shadow: 2px 3px 5px #888; }
.XXX { -moz-box-shadow: 8px 8px 10px #666; -webkit-box-shadow: 3px 3px 8px #666; box-shadow: 3px 3px 8px #666; }
.box { -moz-box-shadow: 3px 3px 4px #999; -webkit-box-shadow: 3px 3px 4px #999; box-shadow: 3px 3px 4px #999; }
.box.caution { -moz-box-shadow: 0px 0px 5px #000; -webkit-box-shadow: 0px 0px 5px #000; box-shadow: 0px 0px 5px #000; }
.box .metainfo { -moz-box-shadow: 2px 2px 3px #999; -webkit-box-shadow: 2px 2px 3px #999; box-shadow: 2px 2px 3px #999;
background: rgba(0,0,0,0.05); background: -webkit-gradient(linear, left top, left bottom, from(rgba(0,0,0,0.0)), to(rgba(0,0,0,0.1))); background: -moz-linear-gradient(top, rgba(0,0,0,0.0), rgba(0,0,0,0.1)); -webkit-background-origin: border; -moz-background-origin: border; background-origin: border;
}
.box .metainfo.bottom { margin-top: -1.6666em; }

.box.titled.UIpane { -moz-box-shadow: 0px 5px 10px #aaa; -webkit-box-shadow: 0px 5px 10px #aaa; box-shadow: 0px 5px 10px #aaa; }


.box.titled.regexEscapeTool.UIpane textarea { -moz-box-shadow: 0px 0px 2px #c2c2c2; -webkit-box-shadow: 0px 0px 2px #c2c2c2; box-shadow: 0px 0px 2px #c2c2c2; }

table.standard            { -moz-box-shadow: 3px 3px 4px #999; -webkit-box-shadow: 3px 3px 4px #999; box-shadow: 3px 3px 4px #999; }
table.standard caption    { -moz-box-shadow: 0px 0px 0px #000; -webkit-box-shadow: 0px 0px 0px #000; box-shadow: 0px 0px 0px #000; }
table.regexSyntax         { -moz-box-shadow: 3px 3px 4px #999; -webkit-box-shadow: 3px 3px 4px #999; box-shadow: 3px 3px 4px #999; }
table.regexSyntax caption { -moz-box-shadow: 0px 0px 0px #000; -webkit-box-shadow: 0px 0px 0px #000; box-shadow: 0px 0px 0px #000; }

table.standard th, table.regexSyntax th {
text-shadow: rgba(0,0,0,0.33) 0px -1px 0px;
background: #93A5BB;
background: -webkit-gradient(linear, left top, left bottom, from(rgba(190,199,214,1.0)), color-stop(0.5, rgba(155,172,191,1.0)), color-stop(0.5, rgba(147,166,187,1.0)), to(rgba(128,150,176,1.0)));
background: -moz-linear-gradient(top, rgba(190,199,214,1.0), rgba(155,172,191,1.0) 50%, rgba(147,166,187,1.0) 50%, rgba(128,150,176,1.0));
color: #fff;
border-top: 1px solid #b8b8b8; border-top: 1px solid rgba(255,255,255,0.2);
border-bottom: 1px solid #b8b8b8; border-bottom: 1px solid rgba(255,255,255,0.25);
border-left:   1px solid #e0e0e0; border-left:   1px solid rgba(255,255,255,0.15);
border-right:  1px solid #c0c0c0; border-right:  1px solid rgba(0,0,0,0.05);
-webkit-background-origin: border !important;
-moz-background-origin: border !important;
background-origin: border !important;
}

table.standard tr > td:first-child, table.regexSyntax tr > td:first-child { border-left: 1px solid #9BB3CD; }

table.standard td                    { border-bottom: 1px solid #9BB3CD; border-right: 1px solid #9BB3CD; }
table.regexSyntax td                    {  border-bottom: 1px solid #9BB3CD; border-right: 1px solid #9BB3CD; }

table.regexSyntax .highlight { padding: 0.0em 0.625ex 0.1em 0.625ex; border: 1px solid #ddd; -webkit-border-radius: 0.5em; -moz-border-radius: 0.5em; border-radius: 0.5em; }
table.regexSyntax .highlight { border: 1px solid rgba(0,0,0,0.075); background: rgba(0,0,0,0.05); background: -webkit-gradient(linear, left top, left bottom, from(rgba(0,0,0,0.0)), to(rgba(0,0,0,0.1))); background: -moz-linear-gradient(top, rgba(0,0,0,0.0), rgba(0,0,0,0.1)); -moz-box-shadow: 0px 0px 2px rgba(0,0,0,0.375); -webkit-box-shadow: 0px 0px 1px rgba(0,0,0,0.375); box-shadow: 0px 0px 1px rgba(0,0,0,0.375); -webkit-background-origin: border; -moz-background-origin: border; background-origin: border; }

.box .highlight { border: 1px solid rgba(0,0,0,0.075); background: rgba(0,0,0,0.05); background: -webkit-gradient(linear, left top, left bottom, from(rgba(0,0,0,0.0)), to(rgba(0,0,0,0.1))); background: -moz-linear-gradient(top, rgba(0,0,0,0.0), rgba(0,0,0,0.1)); -moz-box-shadow: 0px 0px 2px rgba(0,0,0,0.375); -webkit-box-shadow: 0px 0px 1px rgba(0,0,0,0.375); box-shadow: 0px 0px 1px rgba(0,0,0,0.375); -webkit-background-origin: border; -moz-background-origin: border; background-origin: border; }


table.slate:not(.clipboardExamples) { -moz-box-shadow: 2px 2px 3px #999; -webkit-box-shadow: 2px 2px 3px #999; box-shadow: 2px 2px 3px #999; }

div#shadow { -moz-box-shadow: 0px 2px 3px #bbb; -webkit-box-shadow: 0px 1px 2px #ccc; box-shadow: 0px 1px 2px #ccc; }

.reference > h3.InstanceMethods { margin-top: 2.5em; margin-bottom: 2ex; font-size: 2em; border-bottom: 1px solid black; clear: both; }
.reference > h3 { margin: 2em 0px 0.5em 0px; font-size: 1.4166em; }
.reference > h4 { margin: 2em 0px 0.5em 0px; font-size: 1.25em; }

table.slate                       { border-spacing: 0px; margin: 0px 0px 0.5em 0px; background: #fcfcfc; }
table.slate caption               { margin-bottom: 0.5em; text-align: left; }
table.slate caption > .identifier { font-weight: bold; margin-right: 1.5ex; }

table.slate th                    {
white-space: nowrap; font-size: 0.9167em; padding: 0.1em 0.75ex; text-align: left;
background: #ccc; background: -webkit-gradient(linear, left top, left bottom, from(#dbdbdb), to(#bbb)); background: -moz-linear-gradient(top, #dbdbdb, #bbb);
color: #202020; text-shadow: 1px 1px 1px #cfcfcf; text-shadow: 0px 1px 1px rgba(255,255,255,0.95);
border-bottom: 1px solid #b8b8b8;
border-top:    1px solid #f3f3f3;
border-left:   1px solid #e0e0e0; border-left:  1px solid rgba(255,255,255,0.35);
border-right:  1px solid #c0c0c0; border-right: 1px solid rgba(0,0,0,0.05);
-webkit-background-origin: border !important;
-moz-background-origin: border !important;
background-origin: border !important;
}

table.slate, table.slate tr, table.slate th, table.slate td, table.slate tbody {
-webkit-background-origin: border !important;
-moz-background-origin: border !important;
background-origin: border !important;
}
table.slate td                    {
padding: 0.1em 1.0ex; color: #202020; text-shadow: 0px 1px 0px #fbfbfb; text-shadow: 0px 1px 0px rgba(255,255,255,0.75);
background: #f5f5f5; background: -webkit-gradient(linear, left top, left bottom, from(#fafafa), to(#ebebeb)); background: -moz-linear-gradient(top, #fafafa, #ebebeb); 
border-top:    1px  solid #fbfbfb; border-top:    1px solid rgba(255,255,255,0.25);
border-bottom: 1px  solid #e8e8e8; border-bottom: 1px solid rgba(0,0,0,0.015);
border-left:   1px  solid #f6f6f6; border-left:   1px solid rgba(255,255,255,0.375);
border-right:  1px  solid #ececec; border-right:  1px solid rgba(0,0,0,0.02);
-webkit-background-origin: border !important;
-moz-background-origin: border !important;
background-origin: border !important;
}

table.slate tr:nth-child(odd) > td { text-shadow: 0px 1px 0px #ecf2fc;  background: #dde8fa; background: -webkit-gradient(linear, left top, left bottom, from(#eaf1fb), to(#d1e0f9)); background: -moz-linear-gradient(top, #eaf1fb, #d1e0f9); text-shadow: 0px 1px 0px rgba(255,255,255,0.5);}

table.slate tr:first-child > * { border-top:    1px solid #d0d0d0 !important; }
table.slate tr > *:first-child { border-left:   1px solid #d0d0d0 !important; border-left:   1px solid rgba(0,0,0,0.1) !important; }
table.slate tr > *:last-child  { border-right:  1px solid #d0d0d0 !important; border-right:  1px solid rgba(0,0,0,0.1) !important; }
table.slate tr:last-child > *  { border-bottom: 1px solid #d0d0d0 !important; border-bottom: 1px solid rgba(0,0,0,0.2) !important; }

table.slate, table.slate tbody, div#shadow, div#clip {
-moz-border-radius-topleft:     0.625ex; -webkit-border-top-left-radius:     0.625ex; border-top-left-radius:     0.625ex;
-moz-border-radius-topright:    0.625ex; -webkit-border-top-right-radius:    0.625ex; border-top-right-radius:    0.625ex;
-moz-border-radius-bottomleft:  0.5ex;   -webkit-border-bottom-left-radius:  0.5ex;   border-bottom-left-radius:  0.5ex;
-moz-border-radius-bottomright: 0.5ex;   -webkit-border-bottom-right-radius: 0.5ex;   border-bottom-right-radius: 0.5ex;
}

table.slate tr:first-child { -moz-border-radius-topleft:     0.625ex; -webkit-border-top-left-radius:     0.625ex; border-top-left-radius:     0.625ex;
                             -moz-border-radius-topright:    0.625ex; -webkit-border-top-right-radius:    0.625ex; border-top-right-radius:    0.625ex; }
table.slate tr:last-child  { -moz-border-radius-bottomleft:  0.5ex;   -webkit-border-bottom-left-radius:  0.5ex;   border-bottom-left-radius:  0.5ex;
                             -moz-border-radius-bottomright: 0.5ex;   -webkit-border-bottom-right-radius: 0.5ex;   border-bottom-right-radius: 0.5ex;}

table.slate tr:first-child > *:first-child { -moz-border-radius-topleft:     0.625ex; -webkit-border-top-left-radius:     0.75ex; border-top-left-radius:     0.75ex; }
table.slate tr:first-child > *:last-child  { -moz-border-radius-topright:    0.625ex; -webkit-border-top-right-radius:    0.75ex; border-top-right-radius:    0.75ex; }
table.slate tr:last-child  > *:first-child { -moz-border-radius-bottomleft:  0.5ex;   -webkit-border-bottom-left-radius:  0.5ex;  border-bottom-left-radius:  0.5ex;  }
table.slate tr:last-child  > *:last-child  { -moz-border-radius-bottomright: 0.5ex;   -webkit-border-bottom-right-radius: 0.5ex;  border-bottom-right-radius: 0.5ex;  }

table.slate.clipboardExamples td .regex          { -webkit-transition: opacity 0.33s cubic-bezier(0.2, 0.0, 0.5,  1.0); opacity: 1; }
table.slate.clipboardExamples.inactive td .regex { -webkit-transition: opacity 0.33s cubic-bezier(0.5, 0.0, 0.75, 0.9); opacity: 0 !important; }

table.slate.clipboardExamples        { z-index: 10; position: relative; }
table.slate.clipboardExamples.active { z-index: 99 !important; }
table.slate.clipboardExamples#cbe_bg { z-index: 1; }

table.slate.clipboardExamples.active td .regex { -moz-user-select: text; -webkit-user-select: text; cursor: auto; }
table.slate.clipboardExamples#cbe_bg td > *    { visibility: hidden; }
table.slate.clipboardExamples#cbe_a th, table.slate.clipboardExamples#cbe_b th { visibility: hidden; }

table.slate.clipboardExamples td .regex > del { display: none; }
table.slate.clipboardExamples td .regex > ins { -webkit-transition: color 1s cubic-bezier(0.43, 0, 1.0, 0.75), text-shadow 0.65s cubic-bezier(0.43, 0, 1.0, 0.75); color: #202020; text-decoration: none; }
table.slate.clipboardExamples.inactive td > .regex > ins { color: #f00; text-shadow: 1px 1px 3px rgba(255,0,0,0.66); }

table.slate.clipboardExamples.transparentBackground, table.slate.clipboardExamples.transparentBackground * { border-color: transparent !important; background: transparent !important; }

table.regexList .regexMatch { padding-right: 0.75ex; padding-left: 0.75ex; }
/* even = light, odd = dark */
table.regexList tr:nth-child(odd) .regexMatch { border-right: 1px solid rgba(0,0,0,0.05); border-left: 1px solid rgba(255,255,255,0.5); }
table.regexList tr:nth-child(even) .regexMatch { border-right: 1px solid rgba(0,0,0,0.04); border-left: 1px solid rgba(255,255,255,0.85); }

table.regexList .regexMatch:first-child { padding-left: 0px; border-left: 0px solid transparent !important; }
table.regexList .regexMatch:last-child { padding-right: 0px; border-right: 0px solid transparent !important; }

table.slate.clipboardExamples { font-size: 12px; }

table.slate > tbody > tr > td.code { font-size: 0.8334em; color: #202020; text-shadow: 0px 1px 0px rgba(255,255,255,0.75); }

.tunableBreak { display: none; }
.tbrOn { display: none; }
.tbrOff { display: inline; }
}

/* This causes the ICU regex syntax tables to double up, side-by-side when the view port size > 1200.  Otherwise, one follows the other for readability on small screens. */
@media screen and (max-width: 1100px) {
div.table.regexSyntax, div.table.regexSyntax > .row, div.table.regexSyntax > .row > .cell { display: block; }
div.table.regexSyntax > .row > .cell { width: 100%; }
.metacharacters + .operators { margin-top: 1em; }
.tunableBreak { display: inline; }
.tbrOn { display: inline; }
.tbrOff { display: none; }

}

@media screen and (max-width: 900px) {
table.regexList .regex { white-space: pre-wrap; }
.softNobr    { white-space: pre-wrap; }
}


@media print {

h2   { border-bottom: 1px solid #000; color: #000; }

table.regexList .regex { white-space: pre-wrap; }
table.standard th, table.regexList th { color: #000; border-bottom: 1px solid #9BB3CD; border-right: 1px solid #9BB3CD; border-bottom: 1px solid #919699; border-right: 1px solid #919699; background: #E2E2E2; }

table.standard, table.regexSyntax                       { border-top: 1px solid #919699; border-left: 1px solid #919699; }


.softNobr    { white-space: pre-wrap; }
.tbrOn { display: inline; }
.tbrOff { display: none; }

table.slate                       { border-spacing: 0px; border-top: 1px solid #919699; border-left: 1px solid #919699; }
table.slate caption               { margin-bottom: 0.5em; text-align: left; }
table.slate caption > .identifier { font-weight: bold; margin-right: 1.5ex; }
table.slate tr { -webkit-background-origin: border; -moz-background-origin: border; }
table.slate th                    { padding: 0.3334em 1ex; border-bottom: 1px solid #919699; border-right: 1px solid #919699; background: #E2E2E2; -webkit-background-origin: border; -moz-background-origin: border; }
table.slate td                    { padding-left: 0.75ex; padding-right: 0.75ex; padding-top: 0.1875em; padding-bottom: 0.1875em; border-bottom: 1px solid #919699; border-right: 1px solid #919699; -webkit-background-origin: border; -moz-background-origin: border; }

table.regexList { width: 100%; }

table.regexList .regexMatch { padding-right: 0.75ex; padding-left: 0.75ex; }
table.regexList .regexMatch:first-child { padding-left: 0px; border-left: 0px solid transparent }
table.regexList .regexMatch:last-child { padding-right: 0px; border-right: 0px solid transparent }

table.slate               { -moz-border-radius: 0.5ex; -webkit-border-radius: 0.5ex; border-radius: 0.5ex; }
table.slate tr:first-child > *:first-child { -moz-border-radius-topleft:     0.5ex; -webkit-border-top-left-radius:     0.5ex; border-top-left-radius:     0.5ex; }
table.slate tr:first-child > *:last-child  { -moz-border-radius-topright:    0.5ex; -webkit-border-top-right-radius:    0.5ex; border-top-right-radius:    0.5ex; }
table.slate tr:last-child  > *:first-child { -moz-border-radius-bottomleft:  0.5ex; -webkit-border-bottom-left-radius:  0.5ex; border-bottom-left-radius:  0.5ex; }
table.slate tr:last-child  > *:last-child  { -moz-border-radius-bottomright: 0.5ex; -webkit-border-bottom-right-radius: 0.5ex; border-bottom-right-radius: 0.5ex; }

.screenOnly { display: none; }


body { font: 10pt "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", helvetica, arial, sans-serif; margin: 0px; margin-left: 1.15in;  /*width:100%;*/ /* margin-right: -0.4in;*/ /*margin-right: -1in;*/ /*width: 100%;*/ }
h1 { padding-bottom: 0px; padding-top: 0.5em; margin-top: 2in; margin-bottom: 0.5em; border-top: 1px solid black; font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; font-size: 27pt; }
h2 { page-break-after: avoid; padding-bottom: 3.5em; padding-left: 0.6in; padding-top: 1em; margin-bottom: 2.5em; font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; font-size: 24pt; }
h3, .tasks .header, .guide .seealso > .header { padding-bottom: 0.25em; border-bottom: 1px solid black; page-break-after: avoid; font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; font-size: 18pt; }
h4 { padding-bottom: 0.25em; border-bottom: 1px solid black; page-break-after: avoid; font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; }
h5 { border-bottom: 1px solid black; font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; }

.titlePage h1 { font-size: 27pt; }

.security { padding-left: 0.6in; }
.security > .inner { margin-left: 0.5ex; }
h1, h2, h3, .security { margin-left: -0.6in; }
h1.reference { font-size: 24pt; margin-top: 2.5em; padding-bottom: 4em; padding-left: 0.6in; padding-top: 0px; margin-bottom: 0.5em; border-top: 0px; border-bottom: 1px solid black; }

.reference h2 {
page-break-before: avoid; page-break-after: avoid;
border-bottom: 1px solid black; 
margin-top: 2.0em; margin-bottom: 0.5em;
margin-right: 0px; margin-left: -0.6in;
padding: 0px 0px 0.25em 0px;
font-size: 18pt;
font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; }

A:link, A:link:hover, A:active, A:active:hover, A:visited, A:visited:hover{ text-decoration: none; color: #000; }
a.printURL:after { content: " (" attr(href) ")"; font-size: 85%; font-style: italic; }
a.NBSP_printURL:after { content: "\00A0(" attr(href) ")"; font-size: 85%; font-style: italic; } 
a.printURL_small:after { content: " (" attr(href) ")"; font-size: 66%; font-style: italic; }
a.NBSP_printURL_small:after { content: "\00A0(" attr(href) ")"; font-size: 66%; font-style: italic; } 
a.printURL_verySmall:after { content: " (" attr(href) ")"; font-size: 50%; font-style: italic; overflow: hidden; text-overflow: ellipsis; }
a.NBSP_printURL_verySmall:after { content: "\00A0(" attr(href) ")"; font-size: 50%; font-style: italic; overflow: hidden; text-overflow: ellipsis; }

.overview > .masthead { page-break-after: avoid; padding-bottom: 2.5em; margin-top: 0px; margin-bottom: 1.0em; font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; }

.printPageBreakBefore { page-break-before: always; }
.printPageBreakAfter { page-break-after: always; }

.titlePage .frameworkabstract { margin-left: -0.6in; font-size: 11pt; }
.titlePage .dateAndRevision { font: bold 10pt Helvetica; margin-top: 5.25in; }

table.standard { -moz-box-shadow: 2px 2px 1px #777; -webkit-box-shadow: 2px 2px 1px #777; }
table.regexSyntax { -moz-box-shadow: 2px 2px 1px #777; -webkit-box-shadow: 2px 2px 1px #777; }
table.slate { -moz-box-shadow: 2px 2px 1px #777; -webkit-box-shadow: 2px 2px 1px #777; }
table.regexList { -moz-box-shadow: 2px 2px 1px #777; -webkit-box-shadow: 2px 2px 1px #777; }
table.standard caption { -moz-box-shadow: 0px 0px 0px #000; -webkit-box-shadow: 0px 0px 0px #000; }
table.regexSyntax caption { -moz-box-shadow: 0px 0px 0px #000; -webkit-box-shadow: 0px 0px 0px #000; }
table.slate caption { -moz-box-shadow: 0px 0px 0px #000; -webkit-box-shadow: 0px 0px 0px #000; }
table.regexList caption { -moz-box-shadow: 0px 0px 0px #000; -webkit-box-shadow: 0px 0px 0px #000; }

.table.standard { background-color: white; }

.box .metainfo { font: 6.5pt "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; border-color: #999; background-color: white; }
.box .metainfo.printShadow { -moz-box-shadow: 1px 1px 2px #bbb; -webkit-box-shadow: 1px 1px 2px #bbb; }
.box .highlight { padding-top: 1pt; padding-bottom: 1pt; }

.code, .regex, .regex-textual, .regex-def, .header_file, .file, .build-phase, .xcode-group, .xcode-target, .window-name, .box.sourcecode, .box.shell, .shellFont, .guide .sourceLicense pre, .signature, .block > .section.constants > .constant > .identifier, .dialog-option, .context-menu, .block.typedef > .section.code, .block.typedef > .section.type, .quotedText, .unicodeCharName, .block > .section.declaration, .regexMatch, .unicodeProperty, .consoleText, .section.parameters li > .name { font-size: 0.8334em !important; font-family: "Letter Gothic Std", "Letter Gothic", "LetterGothic", "Courier New", monaco, courier, monospace; }

.regex-def, .cppTunables .cpp_flag, .cppTunables .code { font-size: 8pt !important; }
table.regexSyntax.unicodeProperties .consoleText { font-size: 8pt !important; }

.box .metainfo.noPrintBorder { margin-right: 0px; padding: 0px; border: 0px none transparent; background-color: white; -webkit-border-radius: 0px; -moz-border-radius: 0px; }
.box .metainfo > .continues.above > .info { font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif !important; }

.regex b { font: bold 1.1000em "Letter Gothic Std", "Letter Gothic", "LetterGothic", "Courier New", monaco, courier, monospace; }
.syntax > .specification { font-family: "Letter Gothic Std", "Letter Gothic", "LetterGothic", "Courier New", monaco, courier, monospace; }

.section.parameters ul { margin: 0px 0px 0px 0px; }

.argument { font-family: "Letter Gothic Std", "Letter Gothic", "LetterGothic", "Courier New", monaco, courier, monospace; font-style: italic; font-size:0.85em; }
.signature .argument { font-size: 1.02em; }
/*.signature .argument { font-size: 8pt; }*/
.signature .selector, .signature .function { font-weight: bold; }
.code .cpp_flag    { font-weight: bold; font-size: 95%; }


div.table.regexSyntax, div.table.regexSyntax > .row, div.table.regexSyntax > .row > .cell { display: block; }
div.table.regexSyntax > .row > .cell { width: 100%; }
.metacharacters + .operators { margin-top: 1em; }

.syntax > .specification .parameter, .tasks .header .code, .method .name, .typedef .name { font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: normal; }

.constants > .constant > .identifier, .code, .header_file, .file, .unicodeCharName { color: #000; }
.box.tip        { -webkit-border-radius: 0.85em; -moz-border-radius: 0.85em; }
.box.sourcecode, .box.shell { margin-left: 0px; margin-right: 0px; padding: 0px; border: 1px solid white;  background-color: white; -webkit-border-radius: 0px; }
.box.sourcecode .comment        { font-family: 'Lucida Sans Typewriter Std'; font-size: 8pt !important; }


table, .box, .figure, .seealso, li, p, div.box.sourcecode { page-break-inside: avoid; }
.regexSyntax .metacharacters table { page-break-before: avoid !important; page-break-inside: avoid !important; }

.tasks > .header { font-size: 1.2500em; }
.method > .name, .function > .name, .macro > .name, .typedef > .name { font-size: 1.2em; font-family: "Palatino LT Std", palatino, "Palatino Linotype", "URW Palladio L", "URWPalladioL", "Minion", "Minion Pro", georgia, times, "lucida grande", geneva, helvetica, arial, sans-serif; font-weight: bold; }
.method, .function, .macro, .block.typedef { margin: 1.5em 0px 0px 0px; padding: 1.5em 0px 0px 0px; }


.box.classSpecs { margin-left: 0px; font-size: 1.1em; }
.box.hasRows                                 { border: 0px none transparent; }
.box.hasRows > .row         > .cell          { display: table-cell; padding: 1ex; border: 0px none transparent; }
.box.hasRows > .row.lastRow > .cell          { border: 0px none transparent !important; }

.box.hasRows.zebraRows > .row.odd             { background-color: white;                       }
.box.hasRows           > .row.headerRow       { background-color: white;                       }
.box.hasRows           > .row.headerRow .cell { padding-top: 0.3334em; padding-bottom: 0.3334em; }

.syntax > .specification .optional { -moz-box-shadow: 2px 3px 5px #888; -webkit-box-shadow: 2px 3px 5px #888; }
.box.important, .box.note, .box.warning, .box.tip, .box.small, .box.quote { -moz-box-shadow: 2px 2px 1px #777; -webkit-box-shadow: 2px 2px 1px #777; }
.box.caution { -moz-box-shadow: 0px 0px 5px #000; -webkit-box-shadow: 0px 0px 5px #000; }


ul.overview { margin-left: 4.0ex; }
.printNegLeft { font-size: 0.5em; }
.constants > .constant > .text { margin-left: 0.4in; }
.sourceLicense { page-break-inside: avoid; }

.printImg { width: 100%; }
.guide .seealso > .header { margin-top: 2.0em; margin-bottom: 0.5em; font-size: 1.5834em; }

}

    </style>
    <script type="text/javascript">
var prefs = {
  current: {
    asNSString:              true,
    escapeCopiedRegexes:     true,
    escapeUnicodeCharacters: true,
    smartEscape:             true,
    turnIntoString:          true,
    unicodeInNSStrings:      false,
    useC99:                  false
  },
  defaults: {
    asNSString:              true,
    escapeCopiedRegexes:     true,
    escapeUnicodeCharacters: true,
    smartEscape:             true,
    turnIntoString:          true
  }
};

var ui = {
  e: {
    cbe: { }
  },
  pref: {
    map:      {},
    rows:     [],
    controls: [],
    warnings: []
  },
  state: {
    interactiveInput: {
      updatePending: false
    },
    copyToClipboardHUD: {
      ending:    false,
      displayed: false,
      timeout:   null
    },
    regexTable: {
      readyForTransitions: false,
      timeout:             null,
      last:                "-",
      lastOptions:         prefs
    }
  }
};

var cache = {
  firstByteMark:           [0x00, 0x00, 0xC0, 0xE0, 0xF0, 0xF8, 0xFC],
  calculateStringDiff:     { },
  currentPrefs:            ui.state.regexTable.lastOptions,
  diffString:              { },
  escapedString:           { },
  escapeCharacterEntities: { },
  ui: {
    prefs: {
      prefWarningsHeight: 0
    }
  }
};

var utils = {
  browserInfo: {
    matches: {
      webKit:  navigator.userAgent.match(/AppleWebKit\/(\d+(?:\.\d+)?)\b/),
      safari:  navigator.userAgent.match(/AppleWebKit\/(\d+(?:\.\d+)?)\b.*?\sVersion\/((\d+(?:\.\d+)?)\b([^ ]*))\s.*?\bSafari\/([\d\.]+)\b/),
      xcode:   navigator.userAgent.match(/AppleWebKit\/(\d+(?:\.\d+)?)\b.*?\bXcode\/([\d\.]+)\b/),
      opera:   navigator.userAgent.match(/^Opera\/(\d+(?:\.\d+)?)/),
      mozilla: navigator.userAgent.match(/^Mozilla\/(\d+(?:\.\d+)?)\b.*\srv:(\d+(?:\.\d+)?)/),
      firefox: navigator.userAgent.match(/^Mozilla.*\s\w+\/(\d+)(?:\.(.*))?$/)
    }
  },
  regex: {
    lt:           /\u003c/g,
    gt:           /\003e/g,
    amp:          /\0026/g,
    newline:      /\n/g,
    quote:        /\"/g,
    specialChar:  /(\\{1,1}?)([^\"\\])/g,
    specialCharPlusNewlines: /(?!\\\\[un])([^\\]\\(?=[\"n]))([^\"n])/g,
    escapedChar:  /\\(?![0-7]{3}|[xX][a-fA-F0-9]+|u[a-fA-F0-9]{4}|U[a-fA-F0-9]{8})/g,
    escapedCharPlusNewline:  /\\(?![nvfr]|[0-7]{3}|[xX][a-fA-F0-9]+|u[a-fA-F0-9]{4}|U[a-fA-F0-9]{8})/g,
    escapedHex:   /\\?\\(?:[xX][a-fA-F0-9]+|u[a-fA-F0-9]{4}|U[a-fA-F0-9]{8})/g,
    escapedOctal: /\\[0-7]{3}/g,
    px:           /(.*)px$/,
    hidden:       /\bhidden\b/,
    doNotEscape:  /\bdoNotEscape\b/,
    marginAndOpacityTransition: /\bmarginAndOpacityTransition\b/
  }
};

if((utils.browserInfo.webKit  = (utils.browserInfo.matches.webKit  !== null) ? true : false) === true) { utils.browserInfo.webKitVersion  = utils.browserInfo.matches.webKit[1]; }
if((utils.browserInfo.safari  = (utils.browserInfo.matches.safari  !== null) ? true : false) === true) { utils.browserInfo.safariVersion  = utils.browserInfo.matches.safari[3]; }
if((utils.browserInfo.opera   = (utils.browserInfo.matches.opera   !== null) ? true : false) === true) { utils.browserInfo.operaVersion   = utils.browserInfo.matches.opera[1];  }
if((utils.browserInfo.mozilla = (utils.browserInfo.matches.mozilla !== null) ? true : false) === true) { utils.browserInfo.mozillaVersion = utils.browserInfo.matches.mozilla[1]; utils.browserInfo.geckoVersion = utils.browserInfo.matches.mozilla[2]; utils.browserInfo.firefoxVersion = utils.browserInfo.matches.firefox[1]; }
if((utils.browserInfo.xcode   = (utils.browserInfo.matches.xcode   !== null) ? true : false) === true) {
  utils.browserInfo.xcodeVersion   = utils.browserInfo.matches.xcode[2];
  var wkver = utils.browserInfo.matches.xcode[1], safver = 1;
  utils.browserInfo.safari = true;
  if(wkver >= 419 && wkver < 525) { safver = 2; }
  else if(wkver >= 525 && wkver < 528) { safver = 3; }
  else if(wkver >= 528) { safver = 4; }
  utils.browserInfo.safariVersion = safver;
}

function getWidthInfo(element) {
  var style = document.defaultView.getComputedStyle(element, null);
  var info  = {
    paddingLeft:     style.paddingLeft,     paddingRight:     style.paddingRight, width: style.width, 
    borderLeftWidth: style.borderLeftWidth, borderRightWidth: style.borderRightWidth
  };

  for(var prop in info) {
    if(info[prop] !== undefined) {
      if(info[prop] === "auto") { info[prop] = 0; } else { var pxMatch = info[prop].match(utils.regex.px); if(pxMatch !== null) { info[prop] = Number(pxMatch[1]); } }
    }
  }

  info.elementOuterWidth = (info.borderLeftWidth   + info.borderRightWidth + info.paddingLeft + info.paddingRight);
  info.elementFullWidth  = (info.elementOuterWidth + info.width);

  return(info);
}

function escapeToCharacterEntities(string) {
  if(cache.escapeCharacterEntities[string] === undefined) { cache.escapeCharacterEntities[string] = string.replace(utils.regex.amp, "&amp;").replace(utils.regex.lt, "&lt;").replace(utils.regex.gt, "&gt;"); }
  return(cache.escapeCharacterEntities[string]);
}

function calculateStringDiff(A, B) {
  if((cache.calculateStringDiff[A] !== undefined) && (cache.calculateStringDiff[A][B] !== undefined)) { return(cache.calculateStringDiff[A][B]); }

  var i = 0, j = 0, L = [], D = {A: A, B: B, length: 0, same: [], del: [], ins: []};

  for(var x = -1; x < A.length + 3; x++) { L[x] = []; for (var y = -1; y < B.length + 3; y++) { L[x][y] = 0; } }

  for (i = A.length; i >= 0; i--) {
    for (j = B.length; j >= 0; j--) {
      if(A[i] === B[j]) { L[i][j] = 1 + L[i+1][j+1]; } else { L[i][j] = ((L[i+1][j] > L[i][j+1]) ? L[i+1][j] : L[i][j+1]); }
    }
  }

  i = j = 0;

  while((i <= A.length) && (j <= B.length)) {
    if((i === A.length) && (j === B.length)) { break; }
    if(A[i] === B[j])                        { D.same[D.length] = A[i]; D.length++; i++; j++; }
    else if(L[i+1][j] >= L[i][j+1])          { D.del[D.length]  = A[i]; D.length++; i++;      }
    else                                     { D.ins[D.length]  = B[j]; D.length++; j++;      }
  }

  if(cache.calculateStringDiff[A]    === undefined) { cache.calculateStringDiff[A]    = {}; }
  if(cache.calculateStringDiff[A][B] === undefined) { cache.calculateStringDiff[A][B] = D;  }

  return(D);
}

function diffString(A, B) {
  if((cache.diffString[A] !== undefined) && (cache.diffString[A][B] !== undefined)) { return(cache.diffString[A][B]); }

  var D = calculateStringDiff(A, B), DS = "", lastFrom = 0;

  for(var x = 0; x < D.length; x++) {
         if(D.same[x] !== undefined) { DS += ((lastFrom === 0) ? ""      : (lastFrom === 1) ? "\u003c/ins\u003e"      : "\u003c/del\u003e")      + escapeToCharacterEntities(D.same[x]); lastFrom = 0; }
    else if(D.ins[x]  !== undefined) { DS += ((lastFrom === 0) ? "\u003cins\u003e" : (lastFrom === 1) ? ""            : "\u003c/del\u003e\u003cins\u003e") + escapeToCharacterEntities(D.ins[x]);  lastFrom = 1;  }
    else if(D.del[x]  !== undefined) { DS += ((lastFrom === 0) ? "\u003cdel\u003e" : (lastFrom === 1) ? "\u003c/ins\u003e\u003cdel\u003e" : "")            + escapeToCharacterEntities(D.del[x]);  lastFrom = 2;  }
  }

  DS += ((lastFrom === 0) ? "" : (lastFrom === 1) ? "\u003c/ins\u003e" : "\u003c/del\u003e");

  if(cache.diffString[A]    === undefined) { cache.diffString[A]    = {}; }
  if(cache.diffString[A][B] === undefined) { cache.diffString[A][B] = DS; }

  return(DS);
}

function isSimpleCString(cstr) {
  var escapedArray, i;

  for(i = 0; i < cstr.length; i++) { if(cstr.charCodeAt(i) > 127) { return(false); } }
  if((escapedArray = cstr.match(utils.regex.escapedOctal)) !== null) { for(i = 0; i < escapedArray.length; i++) { if(parseInt(escapedArray[i].substr(1), 8)  >= 0x80) { return(false); } } }
  if((escapedArray = cstr.match(utils.regex.escapedHex))   !== null) { for(i = 0; i < escapedArray.length; i++) { if(escapedArray[i].search(/\\\\/) !== -1) { continue; } if(parseInt(escapedArray[i].substr(2), 16) >= 0x80) { return(false); } } }
  
  return(true);
}

function stringToEscapedString(string, options) {
  if(options.escapeCopiedRegexes !== true) { return(string); }

  if((cache.escapedString[string] !== undefined) && (cache.escapedString[string][options.key] !== undefined)) { return(cache.escapedString[string][options.key]); }

  var es = "", s = string;

  if(options.smartEscape === false) { s = s.replace(/\\/g, "\\\\"); }
  else {
    s = s.replace(/(\\?)(\\(?:x[a-fA-F0-9]{2}|u([a-fA-F0-9]{4})))/g, function(m0, m1, m2, m3) { return(((m1 === "\\") ? m0 : eval("\"" + m2 + "\""))); });

    s = s.replace(/(\\?)(\\(?:U([a-fA-F0-9]{8})))/g, function(m0, m1, m2, m3) {
	    if(m1 === "\\") { return(m0); }
	    var u32 = parseInt(m3, 16);
	    if(u32 > 0xffff) {
	      var ul = "\\u" + ("0000" + (0xd7c0 + (u32 >> 10)).toString(16)).substr(-4,4);
	      var uh = "\\u" + ("0000" + (0xdc00 + (u32 & 0x3ff)).toString(16)).substr(-4,4);
	      return(eval("\"" + ul + uh + "\""));
	    } else { return(eval("\"\\u" + (("0000" + u32.toString(16)).substr(-4,4)) + "\"")); }
	});

    s = s.replace(/(.?)(\\)(?!\\)(u[0-9a-fA-F]{4}|.?)/g, function(m0, m1, m2, m3) { return(((m3.search(/n|u[0-9a-fA-F]{4}/) !== -1) ? m0 : ((((m1 === "\\")) ? "\\\\" : m1) + "\\\\" + m3))) });
  }

  s = s.replace(utils.regex.quote, "\\\""); // "

  for(var i = 0; i < s.length; i++) {
    var u32 = s.charCodeAt(i), u16h = 0, u16l = 0;
    // If u32 is the start of a UTF16 surrogate pair, get the high surrogate and convert to a UTF32 codepoint.
    if(((u16h = u32) >= 0xd800) && (u16h <= 0xdbff)) { u32 = ((u16h - 0xd7c0) << 10) | ((u16l = s.charCodeAt(++i)) - 0xdc00); }

    if((u32 >= 0x20) && (u32 < 0x7f)) { es += String.fromCharCode(u32); } // Use printable 7 bit ascii directly.
    else {
      switch(u32) { // Pretty escape some characters.
	case 10: es += (options.smartEscape ? "\\n" : "\\\\n"); break;
	//case 11: es += (options.smartEscape ? "\\v" : "\\\\v"); break;
	//case 12: es += (options.smartEscape ? "\\f" : "\\\\f"); break;
	//case 13: es += (options.smartEscape ? "\\r" : "\\\\r"); break;	
	default:
	  if(options.escapeUnicodeCharacters === false) {
	    es += String.fromCharCode(u16h);
	    if(u16l !== 0) { es += String.fromCharCode(u16l); }
	  } else {
	    if(options.smartEscape === false) {
	      if(u32 < 0x10000) { es += "\\\\u" + ("0000"     + u32.toString(16)).substr(-4,4); }
	      else              { es += "\\\\U" + ("00000000" + u32.toString(16)).substr(-8,8); }
	    } else {
	      // C99 6.4.3.2, only 0024 '$', 0040 '@', or 0060 '`' can be specified via \u when < \u00a0. 
	      if((options.useC99 === true) && (u32 >= 0xa0)) {
	        if(u32 < 0x10000) { es += "\\u" + ("0000"     + u32.toString(16)).substr(-4,4); }
		else {              es += "\\U" + ("00000000" + u32.toString(16)).substr(-8,8); }
	      } else {
		var x, ch = u32, utf8 = [], bytes = (ch < 0x80) ? 1 : (ch < 0x800) ? 2 : (ch < 0x10000) ? 3 : 4;
		for(x = bytes; x > 0;           x--) { utf8.unshift((ch | ((x > 1) ? 0x80 : cache.firstByteMark[bytes])) & ((x > 1) ? 0xBF : 0xFF)); ch >>= 6; }
		for(x = 0;     x < utf8.length; x++) { es += "\\"+("000" + utf8[x].toString(8)).substr(-3,3); }
	      }
	    }
	  }
      }
    }
  }

  if(options.turnIntoString === true) {
    es = '"' + es + '"';

    if(options.asNSString) { es = ((isSimpleCString(es) || options.unicodeInNSStrings || !options.smartEscape) ? "@" + es : '[NSString stringWithUTF8String:' + es + ']'); }
  }

  if(options.cache === true) {
    if(cache.escapedString[string]              === undefined) { cache.escapedString[string]              = {}; }
    if(cache.escapedString[string][options.key] === undefined) { cache.escapedString[string][options.key] = es; }
  }

  return(es);
}

function updateRegexEscapedExampleTable(uiForCBE) {
  for(var x = 0; x < exampleRegexArray.length; x++) {
    smartElementUpdate(uiForCBE.row[x].regex, "innerHTML", escapeToCharacterEntities(exampleRegexArray[x]));
    smartElementUpdate(uiForCBE.row[x].escape, "innerHTML", escapeToCharacterEntities(exampleRegexArray[x].toPrefsEscapedString()));
  }
}

function updateRegexEscapedExampleTableNew(uiForCBE_a, uiForCBE_b) {
  for(var x = 0; x < exampleRegexArray.length; x++) {
    smartElementUpdate(uiForCBE_b.row[x].escape, "innerHTML", diffString(stringToEscapedString(exampleRegexArray[x], ui.state.regexTable.lastOptions), exampleRegexArray[x].toPrefsEscapedString()));
  }

  uiForCBE_a.table.className = uiForCBE_a.table.className.replace(/\bactive\b/, "inactive");
  uiForCBE_b.table.className = uiForCBE_b.table.className.replace(/\binactive\b/, "active");
}

function updateRegexEscapedExamples() {
  var cbe_a = ui.e.cbe.a, cbe_b = ui.e.cbe.b;

  if(ui.state.regexTable.last === "a") { updateRegexEscapedExampleTableNew(cbe_a, cbe_b); ui.state.regexTable.last = "b"; }
  else                                 { updateRegexEscapedExampleTableNew(cbe_b, cbe_a); ui.state.regexTable.last = "a"; }
  ui.state.regexTable.lastOptions = cache.currentPrefs;
}

function removeClassFromElement(classToRemove, element) {
  var classMatch, left = new RegExp("\\s?\\b" + classToRemove + "\\b"), right = new RegExp("\\b" + classToRemove + "\\b\\s?");
  if((classMatch = element.className.match(new RegExp("(\\s?)\\b" + classToRemove + "\\b(\\s?)"))) !== null) {
    element.className = element.className.replace((((classMatch[1] !== undefined) && (classMatch[1].length > 0)) ? left : right), "");
  }
}

function setTransitionElement(element, visible, height) {
  if(visible === true) {
    if(element.className.search(utils.regex.hidden) !== -1) { removeClassFromElement("hidden", element); }
    smartElementUpdate(element.style, "marginBottom", "0px");
  } else {
    if(element.className.search(utils.regex.hidden) === -1) { element.className += " hidden"; }
    smartElementUpdate(element.style, "marginBottom", "-" + height + "px");
  }
}

function smartElementUpdate(e, i, val) { if(e[i] !== val) { e[i] = val; } } 

function updatePrefsUI() {
  var e, x;
  
  for(x = 0; x < ui.pref.controls.length; x++) { if((e = ui.pref.controls[x]).nodeName === "SELECT") { continue; } smartElementUpdate(e, "checked", prefs.current[ui.pref.map[e.id]]); }

  if(prefs.current.escapeCopiedRegexes === false) {
    smartElementUpdate(ui.e.copyRegexPrefsStyle[0], "selected", true);
    smartElementUpdate(ui.e.copyRegexPrefsStyle[1], "selected", false);
    smartElementUpdate(ui.e.copyRegexPrefsStyle[2], "selected", false);
    smartElementUpdate(ui.e.copyRegexPrefsStyle[3], "selected", false);
    for(x = 0; x < ui.pref.controls.length; x++) { if((e = ui.pref.controls[x]).nodeName === "SELECT") { continue; } smartElementUpdate(e, "disabled", true); }
    for(x = 0; x < ui.pref.rows.length; x++) { smartElementUpdate(ui.pref.rows[x], "className", "copyRegexPrefsRow disabledPref"); }
  } else {
    var turnIntoNSString = (prefs.current.turnIntoString && prefs.current.asNSString);

    smartElementUpdate(ui.e.copyRegexPrefsStyleRow,                   "className", "copyRegexPrefsRow enabledPref");
    smartElementUpdate(ui.e.copyRegexPrefsStyle[0],                   "selected", false);
    smartElementUpdate(ui.e.copyRegexPrefsStyle[1],                   "selected", !prefs.current.turnIntoString);
    smartElementUpdate(ui.e.copyRegexPrefsStyle[2],                   "selected", prefs.current.turnIntoString && !prefs.current.asNSString);
    smartElementUpdate(ui.e.copyRegexPrefsStyle[3],                   "selected", turnIntoNSString);

    smartElementUpdate(ui.e.copyRegexPrefsSmartEscape,                "disabled", false);
    smartElementUpdate(ui.e.copyRegexPrefsSmartEscapeRow,             "className", "copyRegexPrefsRow enabledPref");

    //smartElementUpdate(ui.e.copyRegexPrefsEscapeUnicodeCharacters,    "disabled", false);
    //smartElementUpdate(ui.e.copyRegexPrefsEscapeUnicodeCharactersRow, "className", "copyRegexPrefsRow enabledPref");

    smartElementUpdate(ui.e.copyRegexPrefsUseC99,                     "disabled", !prefs.current.smartEscape || !prefs.current.escapeUnicodeCharacters);
    smartElementUpdate(ui.e.copyRegexPrefsUseC99Row,                  "className", ((prefs.current.smartEscape && prefs.current.escapeUnicodeCharacters) ? "copyRegexPrefsRow enabledPref" : "copyRegexPrefsRow disabledPref"));

    smartElementUpdate(ui.e.copyRegexPrefsUnicodeInNSStrings,         "disabled", !turnIntoNSString || !prefs.current.smartEscape);
    smartElementUpdate(ui.e.copyRegexPrefsUnicodeInNSStringsRow,      "className", ((turnIntoNSString && prefs.current.smartEscape) ? "copyRegexPrefsRow enabledPref" : "copyRegexPrefsRow disabledPref"));
  }

  if(ui.state.regexTable.readyForTransitions === true) {
    var showPrefWarnings = false, showSmartEscapeWarning = false, showNSStringUnicodeWarning = false, showC99Warning = false;

    if(prefs.current.escapeCopiedRegexes === true) {
      showSmartEscapeWarning     = (!ui.e.copyRegexPrefsSmartEscape.disabled        && prefs.current.smartEscape);
      showNSStringUnicodeWarning = (!ui.e.copyRegexPrefsUnicodeInNSStrings.disabled && prefs.current.unicodeInNSStrings);
      showC99Warning             = (!ui.e.copyRegexPrefsUseC99.disabled             && prefs.current.useC99);
      showPrefWarnings           = (prefs.current.smartEscape || showNSStringUnicodeWarning || showC99Warning);
    }

    setTransitionElement(ui.e.smartEscapeWarning,     showSmartEscapeWarning,     cache.ui.prefs.smartEscapeWarning);
    setTransitionElement(ui.e.c99Warning,             showC99Warning,             cache.ui.prefs.c99Warning);
    setTransitionElement(ui.e.nsstringUnicodeWarning, showNSStringUnicodeWarning, cache.ui.prefs.nsstringUnicodeWarning);
    setTransitionElement(ui.e.prefWarnings,           showPrefWarnings,           cache.ui.prefs.prefWarningsHeight);
  }
  
  updateRegexEscapedExamples();
  
  ui.e.interactiveEscapedOutput.innerHTML = escapeToCharacterEntities(ui.e.interactiveEscapedInput.value.toPrefsEscapedString());
}

function prefsEscapedStringOptions() {
  var prop, options = {}, prefsArray = [];
  for(prop in prefs.current) { options[prop] = prefs.current[prop]; prefsArray.push(prefs.current[prop]); }
  options.key = prefsArray.join("");
  return(options);
}

String.prototype.toPrefsEscapedString = function () {
  if(utils.browserInfo.opera === true) { cache.currentPrefs.cache = true; }
  else { if(String.prototype.toPrefsEscapedString.caller) { cache.currentPrefs.cache = (((String.prototype.toPrefsEscapedString.caller.caller)) ? true : false); } }
  return((prefs.current.escapeCopiedRegexes !== true) ? this : stringToEscapedString(this, cache.currentPrefs));
};

function setPrefsCookie() {
  var distantFuture = new Date(), prefsArray = [], prop;
  distantFuture.setFullYear(2038);
  for(prop in prefs.current) { prefsArray.push(prop + ": " + prefs.current[prop]); }
  document.cookie    = 'prefs="' + escape(prefsArray.join(", ")) + '"; expires=' + distantFuture.toGMTString();
  cache.currentPrefs = prefsEscapedStringOptions();
  updatePrefsUI();
}

function setPrefsFromCookie() {
  var prefsCookie = document.cookie.match(/prefs=\"(.*)\";?/);
  if(prefsCookie !== null) {
    var evalPrefs = "var prefsFromCookie = {" + unescape(prefsCookie[1]) + "};\n" + prefs.setFromCookie;
    try { eval(evalPrefs); }
    catch(e) {
      console.warn("Unable to set copy to clipboard preference from cookie.  Resetting prefs cookie.");
      console.debug("eval '" + evalPrefs + "' = " + e);
      if(console.dir) { console.dir(e); }
      document.cookie = 'prefs="";';
    }
  }

  for(var prop in prefs.defaults) { var cp = prefs.current[prop]; if((cp !== false) && (cp !== true)) { cp = prefs.defaults[prop]; } }
  cache.currentPrefs = prefsEscapedStringOptions();
  setPrefsCookie();
}

function timestampString() {
  var now = new Date();
  return(now.getFullYear() + "-" + ("00" + now.getMonth()).substr(-2,2) + "-" + ("00" + now.getDay()).substr(-2,2) + " " + ("00" + now.getHours()).substr(-2,2) + ":" + ("00" + now.getMinutes()).substr(-2,2) + ":" + ("00" + now.getSeconds()).substr(-2,2) + "." + ("000" + now.getMilliseconds()).substr(-3,3) + " ");
}

function cleanupColorTransition(element) {
  var now     = ["pulseOutline",  "transitionColor"];
  var delayed = ["transitionRed", "transitionGreen", "transitionBlue", "pulseOutlineRed"];

  now.forEach(function(what)     { removeClassFromElement(what, element); });
  delayed.forEach(function(what) { window.setTimeout(function() { removeClassFromElement(what, element); }, 1); });
}

function endTransitionColor(event) { cleanupColorTransition(event.target); }

function setCopyToClipboardHUD(hudString) {
  if(ui.state.copyToClipboardHUD.displayed === true) {
    window.clearTimeout(ui.state.copyToClipboardHUD.timeout);
    ui.state.copyToClipboardHUD.timeout = null;
    
    ui.e.copyToClipboardHUD.style.top = window.pageYOffset + "px";
    var originalWidth                 = ui.e.copyToClipboardHUD.style.width;
    removeClassFromElement("copyToClipboardHUDAnimate", ui.e.copyToClipboardHUD);
    
    window.setTimeout(function() {
	    ui.e.copyToClipboardHUD.style.width = "";
	    ui.e.copyToClipboardHUDRegex.replaceChild(document.createTextNode(hudString), ui.e.copyToClipboardHUDRegex.childNodes[0]);
	    var updateWidth                     = Math.min(Number(ui.e.copyToClipboardHUD.clientWidth), Math.floor(window.outerWidth * 0.9));
	    var updateLeft                      = ((Number(document.width) / 2) - (updateWidth / 2));
	    ui.e.copyToClipboardHUD.style.width = originalWidth;
	    
	    window.setTimeout(function () {
		    ui.e.copyToClipboardHUD.className += " copyToClipboardHUDAnimate";
		    window.setTimeout(function () {
			    ui.e.copyToClipboardHUD.style.left  = updateLeft  + "px";
			    ui.e.copyToClipboardHUD.style.width = updateWidth + "px";
			}, 3);
		}, 5);
	}, 7);
  } else {
    ui.state.copyToClipboardHUD.displayed = true;

    ui.e.copyToClipboardHUDRegex.replaceChild(document.createTextNode(hudString), ui.e.copyToClipboardHUDRegex.childNodes[0]);
    
    smartElementUpdate(ui.e.copyToClipboardHUD.style, "display", "block");
    smartElementUpdate(ui.e.copyToClipboardHUD.style, "position", "absolute");
    
    ui.e.copyToClipboardHUD.style.top   = (window.pageYOffset +1) + "px";
    var updateWidth                     = Math.min(Number(ui.e.copyToClipboardHUD.clientWidth), Math.floor(window.outerWidth * 0.9));
    var updateLeft                      = ((Number(document.width) / 2) - (updateWidth / 2));    ui.e.copyToClipboardHUD.style.left  = updateLeft  + "px";
    ui.e.copyToClipboardHUD.style.width = updateWidth + "px";
    window.setTimeout(function() { ui.e.copyToClipboardHUD.className += " copyToClipboardHUDAnimate"; }, 7);
  }
  
  ui.state.copyToClipboardHUD.timeout = window.setTimeout(function() {
	  ui.e.copyToClipboardHUD.style.top   = (window.pageYOffset - (ui.e.copyToClipboardHUD.clientHeight + 10)) + "px";
	  ui.state.copyToClipboardHUD.ending  = true;
	  ui.state.copyToClipboardHUD.timeout = window.setTimeout(function() {
		  removeClassFromElement("copyToClipboardHUDAnimate", ui.e.copyToClipboardHUD);
		  ui.e.copyToClipboardHUD.style.display = "none";
		  ui.state.copyToClipboardHUD.ending    = false;
		  ui.state.copyToClipboardHUD.displayed = false;
		  ui.state.copyToClipboardHUD.timeout   = null;
		  ui.e.copyToClipboardHUD.style.top     = "";
		  ui.e.copyToClipboardHUD.style.left    = "";
		  ui.e.copyToClipboardHUD.style.width   = "";
	      }, 251);
      }, 3001);
}

function flattenChildren(element) {
  var flatArray = [element];
  for(var x = 0; x < element.children.length; x++) {
    var child = element.children[x];
    if(child.children.length > 0) { flatArray = flatArray.concat(flattenChildren(child)); } else { flatArray.push(child); }
  }
  return(flatArray);
}

function copySelectionToClipboard(element, event) {
  var selection        = window.getSelection();
  var selectionRange   = selection.getRangeAt(0);
  var selectionElement = selectionRange.commonAncestorContainer;
  var selectionParent  = selectionElement.parentNode;

  var isTextArea = (element.isSameNode(ui.e.interactiveEscapedInput) ? true : false);

  if((prefs.current.escapeCopiedRegexes !== false) && ((window.getSelection().rangeCount === 1) || (isTextArea === true)))  {

    if((selectionElement.childNodes.length !== 0) && (isTextArea !== true)) {
      // Check and see if we can narrow things down a bit.
      // For example, tripple clicking a regex in one of the cookbook tables selects the regex + a bit of the cell.  
      // We can safely narrow things down to just the whole regex in that case.

      var regexArray = selectionElement.getElementsByClassName("regex");

      if(regexArray.length !== 1) {
	var intersectionArray = [];
	intersectionArray = flattenChildren(selectionElement).filter(function(e,i,a) { return(selectionRange.intersectsNode(e) && (e.childNodes.length === 1) && (e.childNodes[0].nodeName === "#text") && (selectionRange.isPointInRange(e.childNodes[0], 0) || selectionRange.isPointInRange(e.childNodes[0], e.childNodes[0].length))); });
	if(intersectionArray.length !== 1) { return; }
	regexArray       = intersectionArray;
	selectionRange.selectNodeContents(regexArray[0]);
	selectionElement = regexArray[0].childNodes[0];
	selectionParent  = regexArray[0];
      }

      if(selectionRange.toString() != regexArray[0].childNodes[0].textContent) { return; }
      selectionParent  = regexArray[0];
      selectionElement = selectionParent.childNodes[0];
      if(selectionElement.childNodes.length !== 0) { return; }
      selectionRange.selectNodeContents(selectionElement);
    }

    var copyString = selectionRange.toString().toPrefsEscapedString();
    event.clipboardData.setData("text/plain", copyString);
    event.preventDefault();

    setCopyToClipboardHUD(copyString);

    if(isTextArea === true) {
      cleanupColorTransition(element);
		
      window.setTimeout(function() { 
	      element.className += " pulseOutlineRed";
	      window.setTimeout(function() {
		      element.className += " pulseOutline";
		      window.setTimeout(function() { removeClassFromElement("pulseOutlineRed", element); }, 17);
		  }, 13);
	  }, 11);
      
      element.addEventListener('webkitTransitionEnd', endTransitionColor);
      window.setTimeout(function() { cleanupColorTransition(element); }, 613.0);
    } else {
      var clonedSelectionElement = selectionElement.cloneNode();
      var text                   = selectionElement.textContent, start = selectionRange.startOffset, end = selectionRange.endOffset;
      var startNode              = document.createTextNode(text.substring(0, start));
      var midNode                = document.createTextNode(text.substring(start, end));
      var endNode                = document.createTextNode(text.substring(end));
      var spanNode               = document.createElement("span");
      spanNode.appendChild(midNode);

      while(selectionParent.childNodes.length > 0) { selectionParent.removeChild(selectionParent.childNodes[0]); }
      selectionParent.appendChild(startNode);
      selectionParent.appendChild(spanNode);
      selectionParent.appendChild(endNode);

      spanNode.style.WebkitBoxShadow = "0px 0px 12px rgba(255,0,0,1.0)";
      spanNode.style.background      = "highlight !important";

      window.setTimeout(function() {
	      spanNode.className = "pulseOutline";
	      window.setTimeout(function() { spanNode.style.WebkitBoxShadow = "0px 0px 12px rgba(255,0,0,0.0)"; }, 5.0);
	  }, 3.0);
      
      window.setTimeout(function() {
	      while(selectionParent.childNodes.length > 0) { selectionParent.removeChild(selectionParent.childNodes[0]); }
	      selectionParent.appendChild(clonedSelectionElement);

	      var origNode = selectionParent.childNodes[0], resetRange = document.createRange();
	      resetRange.setStart(origNode, start);
	      resetRange.setEnd(origNode, end);
	      selection.removeAllRanges();
	      selection.addRange(resetRange);
	  }, 607);
    }
  }
}

function buildPreviewTables(tableID, tableAttributesString, regexArray) {
  var rowArray = [], maxLength = 0, x;

  for(x = 0; x < regexArray.length; x++) {
    var regexLength = stringToEscapedString(regexArray[x], { escapeRegex: true, useC99: false, asNSString: true, unicodeInNSStrings: false }).length;
    maxLength = (maxLength < regexLength) ? regexLength : maxLength;
  }
  maxLength -= 2;
  
  rowArray.push("\u003ctable class=\"slate clipboardExamples\" id=\"" + tableID + "\" " + tableAttributesString + "\u003e");
  rowArray.push("  \u003ctr\u003e\u003cth id=\"" + tableID + "_th_0\"\u003eSelection\u003c/th\u003e\u003cth id=\"" + tableID + "_th_1\"\u003eCopied to clipboard as&hellip;\u003c/th\u003e\u003c/tr\u003e");
  for(x = 0; x < regexArray.length; x++) { rowArray.push("  \u003ctr id=\"" + tableID + "_row_" + x + "\"\u003e\u003ctd id=\"" + tableID + "_td_0_" + x + "\" class='unescaped'\u003e\u003cspan class=\"regex\" id=\"" + tableID + "_regex_" + x + "\"\u003e&nbsp;\u003c/span\u003e\u003c/td\u003e\u003ctd id=\"" + tableID + "_td_1_" + x + "\" class='escaped'\u003e\u003cspan class=\"regex doNotEscape\" id=\"" + tableID + "_escape_" + x + "\"\u003e&nbsp;\u003c/span\u003e\u003c/td\u003e\u003c/tr\u003e"); }
  rowArray.push("\u003c/table\u003e");

  return(rowArray.join("\n"));
}

function copyRegexPrefsStyleChanged() {
  switch(ui.e.copyRegexPrefsStyle.options.selectedIndex) {
    case 0: prefs.current.escapeCopiedRegexes = false; prefs.current.turnIntoString = false; prefs.current.asNSString = false; break;
    case 1: prefs.current.escapeCopiedRegexes = true;  prefs.current.turnIntoString = false; prefs.current.asNSString = false; break;
    case 2: prefs.current.escapeCopiedRegexes = true;  prefs.current.turnIntoString = true;  prefs.current.asNSString = false; break;
    case 3: prefs.current.escapeCopiedRegexes = true;  prefs.current.turnIntoString = true;  prefs.current.asNSString = true;  break;
  }
  setPrefsCookie();
}

function interactiveEscapedInputChanged() {
  if(ui.state.interactiveInput.updatePending === false) {
    window.setTimeout(function() {
	    ui.e.interactiveEscapedOutput.innerHTML = escapeToCharacterEntities(ui.e.interactiveEscapedInput.value.toPrefsEscapedString());
	    ui.state.interactiveInput.updatePending = false;
	}, 127.0);
    ui.state.interactiveInput.updatePending = true;
  }
}

function initUIForCBE(id) {
  ui.e.cbe[id]       = {};
  ui.e.cbe[id].table = document.getElementById("cbe_"+id);;

  ui.e.cbe[id].th    = {};
  ui.e.cbe[id].th[0] = document.getElementById("cbe_"+id+"_th_0");
  ui.e.cbe[id].th[1] = document.getElementById("cbe_"+id+"_th_1");

  ui.e.cbe[id].row   = {};

  for(var x = 0; x < exampleRegexArray.length; x++) {
    ui.e.cbe[id].row[x]        = {};
    ui.e.cbe[id].row[x].td     = {};

    ui.e.cbe[id].row[x].tr     = document.getElementById("cbe_"+id+"_row_"    + x);
    ui.e.cbe[id].row[x].td[0]  = document.getElementById("cbe_"+id+"_td_0_"   + x);
    ui.e.cbe[id].row[x].td[1]  = document.getElementById("cbe_"+id+"_td_1_"   + x);
    ui.e.cbe[id].row[x].regex  = document.getElementById("cbe_"+id+"_regex_"  + x);
    ui.e.cbe[id].row[x].escape = document.getElementById("cbe_"+id+"_escape_" + x);
  }
}

function sheetIndexAndRuleIndexOfCSSRule(name) {
  for(var x = 0; x < document.styleSheets.length; x++) {
    var sheet = document.styleSheets[x];
    for(var i = 0; i < sheet.cssRules.length; i++) { if(sheet.cssRules[i].selectorText === name) { return({sheet: x, rule: i}); } }
  }
  return(null);
}

function deleteCSSRule(name) {
  var sheetAndRule;
  if((sheetAndRule = sheetIndexAndRuleIndexOfCSSRule(name)) !== null) { document.styleSheets[sheetAndRule.sheet].deleteRule(sheetAndRule.rule); }
}


function setExampleTablesWidth(width) {
  for(var x = 0; x < exampleRegexArray.length; x++) {
    ui.e.cbe.bg.row[x].td[1].style.width    = width;
    ui.e.cbe.a.row[x].td[1].style.width     = width;
    ui.e.cbe.b.row[x].td[1].style.width     = width;
    
    ui.e.cbe.bg.row[x].td[1].style.maxWidth = width;
    ui.e.cbe.a.row[x].td[1].style.maxWidth  = width;
    ui.e.cbe.b.row[x].td[1].style.maxWidth  = width;
  }
}

function updateExamplesTable() {
  setExampleTablesWidth("");
  setExampleTablesWidth((getWidthInfo(ui.e.topContainer).width - getWidthInfo(ui.e.cbe.bg.row[0].td[0]).elementFullWidth - getWidthInfo(ui.e.cbe.bg.row[0].td[1]).elementOuterWidth) + "px");
}

function updatePrefWarningsMargins() {
  var x, e;

  removeClassFromElement("marginAndOpacityTransition", ui.e.prefWarnings);
  for(x = 0; x < ui.pref.warnings.length; x++) { removeClassFromElement("marginAndOpacityTransition", (e = ui.pref.warnings[x])); smartElementUpdate(e.style, "marginBottom", "0px"); }

  for(x = 0; x < ui.pref.warnings.length; x++) {
    e = ui.pref.warnings[x];
    cache.ui.prefs[e.id] = parseInt(document.defaultView.getComputedStyle(e, null).marginTop, 10) + e.clientHeight;
    e.style.marginBottom = "-" + cache.ui.prefs[e.id] + "px";
  }
  cache.ui.prefs.prefWarningsHeight = Number(ui.e.prefWarnings.clientHeight);
  updatePrefsUI();

  if(ui.state.regexTable.timeout !== null) { window.clearTimeout(ui.state.regexTable.timeout); ui.state.regexTable.timeout = null; }
  ui.state.regexTable.timeout = window.setTimeout(function() {
    ui.state.regexTable.timeout = null;
    if(ui.e.prefWarnings.className.search(utils.regex.marginAndOpacityTransition) === -1) { ui.e.prefWarnings.className += " marginAndOpacityTransition"; }
    for(var x = 0; x < ui.pref.warnings.length; x++) { if(ui.pref.warnings[x].className.search(utils.regex.marginAndOpacityTransition) === -1) { ui.pref.warnings[x].className += " marginAndOpacityTransition"; } } }, 31);

}

function handleResize() {
  updateExamplesTable();
  updatePrefWarningsMargins();
}

function initEnhancedCopyToClipboard() {
  var x, e, eArray = ["prefWarnings", "interactiveEscapedInput", "interactiveEscapedOutput", "copyToClipboardHUD", "copyToClipboardHUDTop", "copyToClipboardHUDRegex", "topContainer"];
  
  for(x = 0; x < eArray.length; x++) { e = eArray[x]; ui.e[e] = document.getElementById(e); }
  for(x = 0, eArray = document.getElementsByClassName("copyRegexPrefsRow");     x < eArray.length; x++) { e = eArray[x]; ui.e[e.id] = e; ui.pref.rows.push(e); }
  for(x = 0, eArray = document.getElementsByClassName("copyRegexPrefsControl"); x < eArray.length; x++) { e = eArray[x]; ui.e[e.id] = e; ui.pref.controls.push(e); }
  for(x = 0, eArray = document.getElementsByClassName("copyRegexPrefsWarning"); x < eArray.length; x++) { e = eArray[x]; ui.e[e.id] = e; ui.pref.warnings.push(e); }

  for(x = 0, eArray = ui.pref.controls; x < eArray.length; x++) {
    if((e = eArray[x]).nodeName === "SELECT") { continue; }
    var m = e.id.match(/copyRegexPrefs(.)(.*)/);
    var n = m[1].toLowerCase() + m[2];
    ui.pref.map[e.id] = n;
    eval("top." + e.id + "Changed = function() { prefs.current." + n + " = ui.e." + e.id + ".checked; setPrefsCookie(); }; ui.e." + e.id + ".addEventListener('change', top." + e.id + "Changed, false); ui.e." + e.id + "Row.getElementsByClassName('UIcontrolLabel')[0].childNodes[0].addEventListener('click', function() { ui.e." + e.id + ".checked = !ui.e." + e.id + ".checked; top." + e.id + "Changed(); }, false);");
    if(prefs.current[n]  === undefined) { prefs.current[n]  = false; }
    if(prefs.defaults[n] === undefined) { prefs.defaults[n] = false; }
  }

  ui.e.copyRegexPrefsStyle.addEventListener("change", copyRegexPrefsStyleChanged, false);
  ui.e.interactiveEscapedInput.addEventListener("keyup", interactiveEscapedInputChanged, false);
 
  var prop, prefsArray = [];
  for(prop in prefs.defaults) { prefsArray.push(prop + ": prefsFromCookie." + prop); }
  prefs.setFromCookie = "prefs.current = { " + prefsArray.join(", ") + "};";

  ui.e.interactiveEscapedInput.addEventListener("input", interactiveEscapedInputChanged, false);

  initUIForCBE("bg");
  initUIForCBE("a");
  initUIForCBE("b");

  var cbe_bg = ui.e.cbe.bg, cbe_a = ui.e.cbe.a, cbe_b = ui.e.cbe.b;

  setPrefsFromCookie();

  for(x = 0; x < exampleRegexArray.length; x++) {
    cbe_bg.row[x].regex.innerHTML  = escapeToCharacterEntities(exampleRegexArray[x]);
    cbe_bg.row[x].escape.innerHTML = escapeToCharacterEntities(exampleRegexArray[x].toPrefsEscapedString());
  }

  deleteCSSRule(".safariOnly");
  deleteCSSRule(".enhancedCopyOnly");

  updateRegexEscapedExampleTable(cbe_bg);
  updateRegexEscapedExampleTable(cbe_a);
  updateRegexEscapedExampleTable(cbe_b);

  cbe_a.table.style.marginTop = "-" + cbe_bg.table.clientHeight + "px";
  cbe_b.table.style.marginTop = "-" + cbe_bg.table.clientHeight + "px";

  cbe_a.table.className += " transparentBackground";
  cbe_b.table.className += " transparentBackground";

  updateExamplesTable();

  addEventListener("resize", handleResize, false);

  for(x = 0, eArray = document.getElementsByClassName("regex");       x < eArray.length; x++) {
    if(eArray[x].className.search(utils.regex.doNotEscape) === -1) { eArray[x].addEventListener('copy', function(event) { copySelectionToClipboard(this, event); }, false); }
  }

  for(x = 0, eArray = document.getElementsByClassName("copyAsRegex"); x < eArray.length; x++) {
    if(eArray[x].className.search(utils.regex.doNotEscape) === -1) { eArray[x].addEventListener('copy', function(event) { copySelectionToClipboard(this, event); }, false); }
  }

  ui.state.regexTable.readyForTransitions = true;

  window.onscroll = function() {
      if(ui.state.copyToClipboardHUD.displayed === true) {
	window.clearTimeout(ui.state.copyToClipboardHUD.timeout);
	ui.state.copyToClipboardHUD.timeout = null;
	removeClassFromElement("copyToClipboardHUDAnimate", ui.e.copyToClipboardHUD);
	
	window.setTimeout(function() {
		ui.state.copyToClipboardHUD.ending    = false;
		ui.state.copyToClipboardHUD.displayed = false;
		ui.e.copyToClipboardHUD.style.display = "none";
		ui.e.copyToClipboardHUD.style.top     = "";
		ui.e.copyToClipboardHUD.style.left    = "";
		ui.e.copyToClipboardHUD.style.width   = "";
	    }, 1);
      }
  }

  handleResize();

  delete initEnhancedCopyToClipboard;
}
if((utils.browserInfo.safari === true) && (utils.browserInfo.safariVersion >= 3) && (navigator.userAgent.search(/iphone|ipod/i) === -1)) { addEventListener("load", initEnhancedCopyToClipboard, false); }

</script>

    <title>RegexKitLite</title>
  </head>

  <body>

    <div class="printPageBreakAfter titlePage">
      <h1 id="RegexKitLiteGuide"><span class="rkl">RegexKit<i>Lite</i></span></h1>

      <span class="frameworkabstract">Lightweight <span class="hardNobr">Objective-C</span> Regular Expressions for <span class="hardNobr">Mac OS X</span> using the ICU Library</span>
      <div class="printOnly dateAndRevision">2010-04-18, v4.0</div>
    </div>

<div class="printPageBreakAfter">
<h2 id="Introduction">Introduction to <span class="rkl">RegexKit<i>Lite</i></span></h2>

<p>This document introduces <span class="rkl">RegexKit<i>Lite</i></span> for <span class="hardNobr">Mac OS X</span>. <span class="rkl">RegexKit<i>Lite</i></span> enables easy access to regular expressions by providing a number of additions to the standard <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/ObjC_classic/index.html" class="section-link">Foundation</a> <span class="code">NSString</span> class. <span class="rkl">RegexKit<i>Lite</i></span> acts as a bridge between the <span class="code">NSString</span> class and the regular expression engine in the <a href="http://site.icu-project.org/" class="section-link NBSP_printURL">International Components for Unicode</a>, or <span class="new-term">ICU</span>, dynamic shared library that is shipped with <span class="hardNobr">Mac OS X</span>.</p>

<h3 id="Introduction_Highlights">Highlights</h3>

<ul class="square highlights">
<li>Uses the regular expression engine from the ICU library which is shipped with <span class="hardNobr">Mac OS X.</span></li>
<li>Automatically caches compiled regular expressions.</li>
<li>Uses direct access to a strings <span class="code hardNobr">UTF-16</span> buffer if it is available.</li>
<li>Caches the <span class="hardNobr code">UTF-16</span> conversion that is required by the ICU library when direct access to a strings <span class="hardNobr code">UTF-16</span> buffer is unavailable.</li>
<li>Small size makes it ideal for use in iPhone applications.</li>
<li>Multithreading safe.</li>
<li><span class="hardNobr">64-bit</span> support.</li>
<li>Custom DTrace probe points.</li>
<li>Support for <span class="hardNobr">Mac OS X 10.5</span> Garbage Collection.</li>
<li>Support for the Blocks language extension.</li>
<li>Uses <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> for greater speed.</li>
<li>Very easy to use, all functionality is provided by a category extension to the <span class="code">NSString</span> class.</li>
<li>Consists of two files, a header and the <span class="hardNobr">Objective-C</span> source.</li>
<li>Xcode 3 integrated <a href="#NSString_RegexKitLiteAdditions__Xcode3IntegratedDocumentation">documentation available</a>.</li>
<li>Distributed under the terms of the <a href="#LicenseInformation" class="hardNobr section-link">BSD License</a>.</li>
</ul>

<h3>Who Should Read This Document</h3>

<p>This document is intended for readers who would like to be able to use regular expressions in their <span class="hardNobr">Objective-C</span> applications, whether those applications are for the <span class="hardNobr">Mac OS X</span> desktop, or for the iPhone.</p>

<p>This document, and <span class="rkl">RegexKit<i>Lite</i></span>, is also intended for anyone who has the need to search and manipulate <span class="code">NSString</span> objects. If you've ever used the <span class="code">NSScanner</span>, <span class="code">NSCharacterSet</span>, and <span class="code">NSPredicate</span> classes, or any of the the <span class="code">NSString</span> <span class="code">rangeOf&hellip;</span> methods, <span class="rkl">RegexKit<i>Lite</i></span> is for you.</p>

<p>Regular expressions are a powerful way to search, match and extract, and manipulate strings.  <span class="rkl">RegexKit<i>Lite</i></span> can perform many of the same operations that <span class="code">NSScanner</span>, <span class="code">NSCharacterSet</span>, and <span class="code">NSPredicate</span> perform, and usually do it with far fewer lines of code.  As an example, <a href="#RegexKitLiteCookbook_PatternMatchingRecipes_TextFiles_ParsingCSVData" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> Cookbook - Parsing CSV Data</a> contains an example that is just over a dozen lines, but is a full featured CSV, or Comma Separated Value, parser that takes a CSV input and turns it in to a <span class="code">NSArray</span> of <span class="code">NSArray</span>s.</p>

<h3>Organization of This Document</h3>

<p>This document follows the conventions and styles used by Apples documentation and is divided in to two main parts:</p>

<ul class="square highlights">
  <li>The <i>Class Reference</i> part, <a href="#RegexKitLiteNSStringAdditionsReference"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code">NSString</span> Additions Reference</a>.</li>
  <li>The <i>Programming Guide</i> part, which consists of the following chapters:</li>
  <li style="list-style-type: none"><ul class="square highlights" style="list-style-type: circle;">
    <li><a href="#RegexKitLiteOverview"><span class="rkl">RegexKit<i>Lite</i></span> Overview</a></li>
    <li><a href="#UsingRegexKitLite">Using <span class="rkl">RegexKit<i>Lite</i></span></a></li>
    <li><a href="#ICUSyntax">ICU Syntax</a></li>
    <li><a href="#RegexKitLiteCookbook"><span class="rkl">RegexKit<i>Lite</i></span> Cookbook</a></li>
    <li><a href="#AddingRegexKitLitetoyourProject">Adding <span class="rkl">RegexKit<i>Lite</i></span> to your Project</a></li>
  </ul></li>
</ul>

<p>Additional information can be found in the following sections:</p>

<ul class="square highlights">
  <li><a href="#ReleaseInformation">Release Information</a>, which contains the <a href="#ReleaseInformation_40">Release Notes for <span class="rkl">RegexKit<i>Lite</i></span> 4.0</a></li>
<!--  <li><a href="#Epilogue" class="section-link">Epilogue</a> -->
  <li><a href="#LicenseInformation">License Information</a>, which contains the <span class="rkl">RegexKit<i>Lite</i></span> <i>BSD License</i>.</li>
</ul>

<h3 id="Introduction_SupportingRegexKitLitethroughFinancialDonations">Supporting <span class="rkl">RegexKit<i>Lite</i></span> through Financial Donations</h3>

<p>A significant amount of time and effort has gone in to the development of <span class="rkl">RegexKit<i>Lite</i></span>. Even though it is distributed under the terms of the <a href="#LicenseInformation" class="hardNobr section-link">BSD License</a>, you are encouraged to contribute financially if you are using <span class="rkl">RegexKit<i>Lite</i></span> in a profitable commercial application. Should you decide to contribute to <span class="rkl">RegexKit<i>Lite</i></span>, please keep the following in mind:</p>

<div class="table" style="margin-top: -1em; margin-bottom: -1em;">
  <div class="row">
    <div class="cell">
      <ul class="square highlights">
	<li>What it would have cost you in terms of hours, or consultant fees, to develop similar functionality.</li>
	<li>The Ohloh.net metrics do not factor in the cost of writing documentation, which is where most of the effort is spent.</li>
	<li>The target audience for <span class="rkl">RegexKit<i>Lite</i></span> is very small, so there are relatively few units &quot;sold&quot;.</li>
      </ul>
      <p>You can contribute by visiting SourceForge.net&#39;s <a href="http://sourceforge.net/donate/index.php?group_id=204582" class="printURL">donation page for <span class="rkl">RegexKit<i>Lite</i></span></a>.</p>
    </div>
    <div class="cell" style="vertical-align: bottom;">
      <div style="margin-left: 4ex;">
	<div class="centerHack"><div style="margin-bottom: 0.75em;"><a href="http://www.ohloh.net/p/RegexKitLite"><img class="noBorder screenOnly" width="100" height="16" alt="Metrics by Ohloh.net" src=""></a></div></div>
	<div class="centerHack"><div style="margin-bottom: 1em;"><a href="http://sourceforge.net/donate/index.php?group_id=204582"><img alt="Support This Project" width="88" height="32" class="noBorder screenOnly" src=""></a></div></div>
      </div>
    </div>
</div></div>
  
<div class="box important" style="margin-top: 1em"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>You are always required to acknowledge the use of <span class="rkl">RegexKit<i>Lite</i></span> in your product as specified in the terms of the <a href="#LicenseInformation" class="hardNobr section-link">BSD License</a>.</p>
</div></div></div></div>


<h3 id="Introduction_Download">Download</h3>

<p>You can download <span class="rkl">RegexKit<i>Lite</i></span> distribution that corresponds to this version of the documentation <span class="hardNobr">here&mdash;</span> <a href="http://downloads.sourceforge.net/regexkit/RegexKitLite-4.0.tar.bz2" class="printURL file">RegexKitLite-4.0.tar.bz2</a> (<span>139.1K</span>). To be automatically notified when a new version of <span class="rkl">RegexKit<i>Lite</i></span> is available, add the <a href="#NSString_RegexKitLiteAdditions__Xcode3IntegratedDocumentation"><span class="rkl">RegexKit<i>Lite</i></span> documentation feed</a> to Xcode.</p>

<h3 id="Introduction_PDFDocumentation">PDF Documentation</h3>

<p>This document is available in PDF format: <a href="http://downloads.sourceforge.net/regexkit/RegexKitLite-4.0.pdf" class="printURL file">RegexKitLite-4.0.pdf</a> (<span>1.1M</span>).</p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>If you wish to print this document, it is recommend that you use the PDF version.</p>
</div></div></div></div>

<h3>Reporting Bugs</h3>

<p>You can file bug reports, or review submitted bugs, at the following URL: <a href="http://sourceforge.net/tracker/?group_id=204582&amp;atid=990188"><span class="code">http://sourceforge.net/tracker/?group_id=204582&amp;atid=990188</span></a></p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>Anonymous bug reports are no longer accepted due to spam.  A SourceForge.net account is required to file a bug report.</p>
</div></div></div></div>

<h3>Contacting The Author</h3>

<p>The author can be contacted at <a href="mailto:regexkitlite@gmail.com"><span class="code">regexkitlite@gmail.com</span></a>.</p>



</div>

<div class="printPageBreakAfter">
<h2 id="RegexKitLiteOverview"><span class="hardNobr">RegexKit<i class="rk">Lite</i> Overview</span></h2>


<p>While <span class="rkl">RegexKit<i>Lite</i></span> is not a descendant of the <span class="file">RegexKit.framework</span> source code, it does provide a small subset of <a href="http://regexkit.sourceforge.net/" class="section-link">RegexKits</a> <span class="code">NSString</span> methods for performing various regular expression tasks. These include determining the range that a regular expression matches within a string, easily creating a new string from the results of a match, splitting a string in to a <span class="code">NSArray</span> with a regular expression, and performing search and replace operations with regular expressions using common <span class="regex">$</span><span class="argument">n</span> substitution syntax.</p>

<p><span class="rkl">RegexKit<i>Lite</i></span> uses the regular expression provided by the ICU library that ships with <span class="hardNobr">Mac OS X</span>.  The two files, <span class="file">RegexKitLite.h</span> and <span class="file">RegexKitLite.m</span>, and linking against the <span class="file">/usr/lib/libicucore.dylib</span> ICU shared library is all that is required.  Adding <span class="rkl">RegexKit<i>Lite</i></span> to your project only adds a few kilobytes of overhead to your applications size and typically only requires a few kilobytes of memory at run-time.  Since a regular expression must first be compiled by the ICU library before it can be used, <span class="rkl">RegexKit<i>Lite</i></span> keeps a small <span class="hardNobr">4-way</span> set associative cache with a least recently used replacement policy of the compiled regular expressions.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://regexkit.sourceforge.net/" class="section-link">RegexKit Framework</a></li>
    <li><a href="http://site.icu-project.org/" class="section-link">International Components for Unicode</a></li>
    <li><a href="http://www.unicode.org/" class="section-link">Unicode Home Page</a></li>
  </ul>
</div>

<h3>Official Support from Apple for ICU Regular Expressions</h3>

<h4>Mac OS X</h4>

<p>As of <span class="hardNobr">Mac OS X 10.6</span>, the author is not aware of any official support from Apple for linking to the <span class="file">libicucore.dylib</span> library.  On the other hand, the author is unaware of any official prohibition against it, either.  Linking to the ICU library and making use of the ICU regular expression API is slightly different than making use of private, undocumented API's.  There are a number of very good reasons why you shouldn't use private, undocumented API's, such as:</p>

<ul class="square highlights">
  <li>The undocumented, private API is not yet mature enough for Apple to commit to supporting it.  Once an API is made "public", developers expect future versions to at least be compatible with previously published versions.</li>
  <li>The undocumented, private API may expose implementation specific details that can change between versions.  Public API's are the proper "abstraction layer boundary" that allows the provider of the API to hide implementation specific details.</li>
</ul>

<p>The ICU library, on the other hand, contains a "published, public API" in which the ICU developers have committed to supporting in later releases, and <span class="rkl">RegexKit<i>Lite</i></span> uses only these public APIs.  One could argue that Apple is not obligated to continue to include the ICU library in later versions of <span class="hardNobr">Mac OS X</span>, but this seems unlikely for a number of reasons which will not be discussed here. With the introduction of <span class="hardNobr">iPhone OS 3.2</span>, Apple now officially supports iPhone applications linking to the ICU library for the purpose of using its regular expression functionality.  This is encouraging news for <span class="hardNobr">Mac OS X</span> developers if one assumes that Apple will try to keep some kind of parity between the <span class="hardNobr">iPhone OS</span> and <span class="hardNobr">Mac OS X</span> API's.</p>

<h4>iPhone OS < 3.2</h4>

<p>Prior to <span class="hardNobr">iPhone OS 3.2</span>, there was never any official support from Apple for linking to the <span class="file">libicucore.dylib</span> library.  It was unclear if linking to the library would violate the <span class="hardNobr">iPhone OS SDK</span> Agreement prohibition against using undocumented API's, but a large number of iPhone applications choose to use <span class="rkl">RegexKit<i>Lite</i></span>, and the author is not aware of a single rejection because of it.</p>

<h4>iPhone OS &ge; 3.2</h4>

<p>Starting with <span class="hardNobr">iPhone OS 3.2</span>, Apple now officially allows <span class="hardNobr">iPhone OS</span> applications to <a href="http://developer.apple.com/iphone/library/releasenotes/General/WhatsNewIniPhoneOS/Articles/iPhoneOS3_2.html#//apple_ref/doc/uid/TP40009337-SW25">link with the ICU library</a>. The ICU library contains a lot of functionality for dealing with internationalization and localization, but <a href="http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html#//apple_ref/doc/uid/TP40009370-CH8-SW31">Apple only officially permits the use of the ICU Regular Expression functionality</a>.</p>

<p>Apple also provides a way to use ICU based regular expressions from <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/ObjC_classic/index.html" class="section-link">Foundation</a> by adding a new option to <a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/c/tdef/NSStringCompareOptions" class="code">NSStringCompareOptions</a>&ndash; <a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/c/econst/NSRegularExpressionSearch" class="code">NSRegularExpressionSearch</a>. This new option can be used with the <span class="code">NSString</span> <a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/rangeOfString:options:" class="code">rangeOfString:options:</a> method, and the following example of its usage is given:</p>

<div class="box sourcecode">// finds phone number in format nnn-nnn-nnnn
NSRange r;
NSString *regEx = @&quot;{3}-[0-9]{3}-[0-9]{4}&quot;;
r = [textView.text rangeOfString:regEx options:NSRegularExpressionSearch];
if (r.location != NSNotFound) {
    NSLog(@&quot;Phone number is %@&quot;, [textView.text substringWithRange:r]);
} else {
    NSLog(@&quot;Not found.&quot;);
}</div>

<p>At this time, <a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/rangeOfString:options:" class="code">rangeOfString:options:</a> is the only regular expression functionality Apple has added to <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/ObjC_classic/index.html" class="section-link">Foundation</a> and capture groups in a regular expression are not supported.  Apple also gives the following note:</p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>As noted in <a href="http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html#//apple_ref/doc/uid/TP40009370-CH8-SW31">"ICU Regular-Expression Support,"</a> the ICU libraries related to regular expressions are included in <span class="hardNobr">iPhone OS 3.2</span>. However, you should only use the ICU facilities if the <span class="code">NSString</span> alternative is not sufficient for your needs.</p>
</div></div></div></div>

<p><span class="rkl">RegexKit<i>Lite</i></span> provides a much richer API, such as the automatic extraction of a match as a <span class="code">NSString</span>.  Using <span class="rkl">RegexKit<i>Lite</i></span>, the example can be rewritten as:</p>

<div class="box sourcecode">// finds phone number in format nnn-nnn-nnnn
NSString *regEx = @&quot;{3}-[0-9]{3}-[0-9]{4}&quot;;
NSString *match = [textView.text stringByMatching:regEx];
if ([match isEqual:@&quot;&quot;] == NO) {
    NSLog(@&quot;Phone number is %@&quot;, match);
} else {
    NSLog(@&quot;Not found.&quot;);
}</div>

<p>What's more, <span class="rkl">RegexKit<i>Lite</i></span> provides easy access to all the matches of a regular expression in a <span class="code">NSString</span>:</p>

<div class="box sourcecode">// finds phone number in format nnn-nnn-nnnn
NSString *regEx = @&quot;{3}-[0-9]{3}-[0-9]{4}&quot;;
for(NSString *match in [textView.text componentsMatchedByRegex:regEx]) {
    NSLog(@&quot;Phone number is %@&quot;, match);
}</div>

<p>To do the same thing using just <a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/c/econst/NSRegularExpressionSearch" class="code">NSRegularExpressionSearch</a> would require significantly more code and effort on your part.  <span class="rkl">RegexKit<i>Lite</i></span> also provides powerful search and replace functionality:</p>

<div class="box sourcecode">// finds phone number in format nnn-nnn-nnnn
NSString *regEx = @&quot;({3})-([0-9]{3}-[0-9]{4})&quot;;
// and transforms the phone number in to the format of (nnn) nnn-nnnn
NSString *replaced = [textView.text stringByReplacingOccurrencesOfRegex:regEx
                                                             withString:@&quot;($1) $2&quot;];</div>

<p><span class="rkl">RegexKit<i>Lite</i></span> also has a number of performance enhancing features built in such as caching compiled regular expressions.  Although the author does not have any benchmarks comparing <a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/c/econst/NSRegularExpressionSearch" class="code">NSRegularExpressionSearch</a> to <span class="rkl">RegexKit<i>Lite</i></span>, it is likely that <span class="rkl">RegexKit<i>Lite</i></span> outperforms <a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/c/econst/NSRegularExpressionSearch" class="code">NSRegularExpressionSearch</a>.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
  <li><a href="http://developer.apple.com/iphone/library/releasenotes/General/WhatsNewIniPhoneOS/Articles/iPhoneOS3_2.html#//apple_ref/doc/uid/TP40009337-SW25" class="section-link">What's New in iPhone OS - ICU Regular-Expression Support</a></li>
  <li><a href="http://developer.apple.com/iphone/library/releasenotes/General/WhatsNewIniPhoneOS/Articles/iPhoneOS3_2.html#//apple_ref/doc/uid/TP40009337-SW17" class="section-link">What's New in iPhone OS - Foundation Framework Changes</a></li>
  <li><a href="http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html#//apple_ref/doc/uid/TP40009370-CH8-SW31" class="section-link">iPad Programming Guide - ICU Regular-Expression Support</a></li>
  <li><a href="http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html#//apple_ref/doc/uid/TP40009370-CH8-SW33" class="section-link">iPad Programming Guide - Foundation-Level Regular Expressions</a></li>
  <li><a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/c/econst/NSRegularExpressionSearch" class="code">NSRegularExpressionSearch</a></li>
  <li><a href="http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/rangeOfString:options:" class="code">- rangeOfString:options:</a></li>
  </ul>
</div>

<h4>The iPhone 4.0 SDK Agreement</h4>

<p>While <span class="hardNobr">iPhone OS 3.2</span> included official, Apple sanctioned use of linking of the ICU library for the purposes of using the ICU regular expression engine, the <span class="hardNobr">iPhone OS 4.0 SDK</span> included the following change to the <span class="hardNobr">iPhone OS SDK</span> Agreement:</p>

<div class="table"><div class="row"><div class="cell" style="padding-left: 2.5ex; padding-right: 1.5ex;">3.3.1</div><div class="cell"><p style="max-width: 6.125in; text-align: justify;">Applications may only use Documented APIs in the manner prescribed by Apple and must not use or call any private APIs. Applications must be originally written in Objective-C, C, C++, or JavaScript as executed by the iPhone OS WebKit engine, and only code written in C, C++, and Objective-C may compile and directly link against the Documented APIs (e.g., Applications that link to Documented APIs through an intermediary translation or compatibility layer or tool are prohibited).</p></div></div></div>

<p>This raises a number of obvious questions:</p>

<ul class="square highlights">
  <li>Does 3.3.1 apply to <span class="rkl">RegexKit<i>Lite</i></span>?</li>
  <li>Will the use of <span class="rkl">RegexKit<i>Lite</i></span> in an <span class="hardNobr">iPhone OS</span> application be grounds for rejection under 3.3.1?</li>
</ul>


<p>There is considerable speculation as to what is covered by this change, but at the time of this writing, there is no empirical evidence or official guidelines from Apple to make any kind of an informed decision as to whether or not the use of <span class="rkl">RegexKit<i>Lite</i></span> would violate 3.3.1.  It is the authors opinion that <span class="rkl">RegexKit<i>Lite</i></span> could be considered as a <i>compatibility layer</i> between <span class="code">NSString</span> and the now <i>Documented APIs</i> for regular expressions in the ICU library.</p>

<p>It is widely speculated that the motivation for the change to 3.3.1 was to prevent the development of Flash applications for the iPhone.  The author believes that most reasonable people would consider the application of <i>compatibility layer</i> in this context to mean something entirely different than what it means when applied to <span class="rkl">RegexKit<i>Lite</i></span>.</p>

<p>At this time, the author is not aware of a single iPhone application that has been rejected due to the use of <span class="rkl">RegexKit<i>Lite</i></span>.  If your application is rejected due to the use of <span class="rkl">RegexKit<i>Lite</i></span>, please let the author know by emailing <a href="mailto:regexkitlite@gmail.com"><span class="consoleText">regexkitlite@gmail.com</span></a>.  As always, <span style="font-family: courier, monospace">CAVEAT EMPTOR</span>.</p>



  <h3>The Difference Between RegexKit.framework and <span class="rkl">RegexKit<i>Lite</i></span></h3>

  <p>RegexKit.framework and <span class="rkl">RegexKit<i>Lite</i></span> are two different projects.  In retrospect, <span class="rkl">RegexKit<i>Lite</i></span> should have been given a more distinctive name.  Below is a table summarizing some of the key differences between the two:</p>

  <table class="standard">
    <tr><th>&nbsp;</th><th>RegexKit.framework</th><th><span class="rkl">RegexKit<i>Lite</i></span></th></tr>
    <tr><td><b>Regex Library</b></td><td>PCRE</td><td>ICU</td></tr>
    <tr><td><b>Library Included</b></td><td>Yes, built into framework object file.</td><td>No, provided by <span class="hardNobr">Mac OS X.</span></td></tr>
    <tr><td><b>Library Linked As</b></td><td>Statically linked into framework.</td><td>Dynamically linked to <span class="file">/usr/lib/libicucore.dylib.</span></td></tr>
    <tr><td><b>Compiled Size</b></td><td>Approximately <span class="hardNobr">371KB<sup>&dagger;</sup></span> per architecture.</td><td>Very small, approximately <span class="hardNobr">16KB&mdash;20KB<sup>&Dagger;</sup></span> per architecture.</td></tr>
    <tr><td><b>Style</b></td><td>External, linked to framework.</td><td>Compiled directly in to final executable.</td></tr>
    <tr><td><b>Feature Set</b></td><td>Large, with additions to many classes.</td><td>Minimal, <span class="code">NSString</span> only.</td></tr>
  </table>

  <div class="table" style="margin: 1em 0px">
    <div class="row"><div class="cell"><sup>&dagger;</sup></div><div class="cell"><span style="margin:0px 1ex">-</span></div><div class="cell"><span class="hardNobr">Version 0.6.0.</span> About half of the <span class="hardNobr">371KB</span> is the PCRE library.<br>
The default distribution framework shared library file is <span class="hardNobr">1.4MB</span> in size and includes the <span class="quotedText">ppc</span>, <span class="quotedText">ppc64</span>, <span class="quotedText">i386</span>, and <span class="quotedText">x86_64</span> architectures.<br>
If <span class="hardNobr">64-bit</span> support is removed, the framework shared library file size drops to <span class="hardNobr">664KB</span>.</div></div>
    <div class="row"><div class="cell"><sup>&Dagger;</sup></div><div class="cell"><span style="margin:0px 1ex">-</span></div><div class="cell">Since the ICU library is part of <span class="hardNobr">Mac OS X,</span> it does not add to the final size.</div></div>
  </div>

  <h3>Compiled Regular Expression Cache</h3>

<p>The <span class="code">NSString</span> that contains the regular expression must be compiled in to an ICU <a href="http://www.icu-project.org/apiref/icu4c/uregex_8h.html#566882c83d9e4dcf7fb5d8f859625500" class="code">URegularExpression</a>.  This can be an expensive, time consuming step, and the compiled regular expression can be reused again in another search, even if the strings to be searched are different.  Therefore <span class="rkl">RegexKit<i>Lite</i></span> keeps a small cache of recently compiled regular expressions.</p>

<p>The cache is organized as a 4-way set associative cache, and the size of the cache can be tuned with the <span class="hardNobr">pre-processor</span> define <span class="cpp_flag">RKL_CACHE_SIZE</span>.  The default cache size, which should always be a prime number, is set to <span class="code">13</span>.  Since the cache is 4-way set associative, the total number of compiled regular expressions that can be cached is <span class="cpp_flag">RKL_CACHE_SIZE</span> times four, for a total of <span class="code">13 * 4</span>, or <span class="code">52</span>.  The <span class="code">NSString</span> <span class="argument">regexString</span> is mapped to a cache set using modular arithmetic: <span class="hardNobr">Cache set &equiv; <span class="code">[regexString hash]</span> mod <span class="cpp_flag">RKL_CACHE_SIZE</span>,</span> <span class="hardNobr">i.e.</span> <span class="hardNobr"><span class="code">cacheSet = [regexString hash] % 13;</span>.</span>  Since <span class="rkl">RegexKit<i>Lite</i></span> uses <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a>, this is actually coded <span class="hardNobr"> as <span class="code">cacheSet = CFHash(regexString) % <span class="cpp_flag">RKL_CACHE_SIZE</span>;</span>.</span></p>

<p>Each of the four &quot;ways&quot; of a cache set are checked to see if it contains a <span class="code">NSString</span> that was used to create the compiled regular expression that is identical to the <span class="code">NSString</span> for the regular expression that is being checked.  If there is an exact match, then the matching &quot;way&quot; is updated as the most recently used, and the compiled regular expression is used as-is.  Otherwise, the least recently used, or LRU, &quot;way&quot; in the cache set is cleared and replaced with the compiled regular expression for the regular expression that wasn't in the cache.</p>

<p>In addition to the compiled regular expression cache, <span class="rkl">RegexKit<i>Lite</i></span> keeps a small lookaside cache that maps a regular expressions <span class="code">NSString</span> pointer and <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> directly to a cached compiled regular expression. When a regular expressions <span class="code">NSString</span> pointer and <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> is in the lookaside cache, <span class="rkl">RegexKit<i>Lite</i></span> can bypass calling <span class="code">CFHash(regexString)</span> and checking each of the four &quot;ways&quot; in a cache set since the lookaside cache has provided the exact cached compiled regular expression.  The lookaside cache is quite small at just 64 bytes and it was added because <span class="file hardNobr">Shark.app</span> profiling during performance tuning showed that <span class="code hardNobr">CFHash()</span>, while quite fast, was the primary bottleneck when retrieving already compiled and cached regular expressions, typically accounting for &cong;40% of the look up time.</p>

<h4>Regular Expressions in Mutable Strings</h4>

<p>When a regular expression is compiled, an immutable copy of the string is kept.  For immutable <span class="code">NSString</span> objects, the copy is usually the same object with its reference count increased by one.  Only <span class="code">NSMutableString</span> objects will cause a new, immutable <span class="code">NSString</span> to be created.</p>

<p>If the regular expression being used is stored in a <span class="code">NSMutableString</span>, the cached regular expression will continue to be used as long as the <span class="code">NSMutableString</span> remains unchanged.  Once mutated, the changed <span class="code">NSMutableString</span> will no longer be a match for the cached compiled regular expression that was being used by it previously.  Even if the newly mutated strings <span class="code">hash</span> is congruent to the previous unmutated strings <span class="code">hash</span> modulo <span class="cpp_flag">RKL_CACHE_SIZE</span>, that is to say they share the same cache set <span class="hardNobr">(i.e.,</span> <span class="code"><span class="hardNobr">([mutatedString hash] % <span class="cpp_flag">RKL_CACHE_SIZE</span>)</span> == <span class="hardNobr">([unmutatedString hash] % <span class="cpp_flag">RKL_CACHE_SIZE</span>)</span>)</span>, the immutable copy of the regular expression string used to create the compiled regular expression is used to ensure true equality.  The newly mutated string will have to go through the whole regular expression compile and cache creation process.</p>

<p>This means that <span class="code">NSMutableString</span> objects can be safely used as regular expressions, and any mutations to those objects will immediately be detected and reflected in the regular expression used for matching.</p>

<h4>Searching Mutable Strings</h4>


<p>Unfortunately, the ICU regular expression API requires that the compiled regular expression be <span class="hardNobr">"set"</span> to the string to be searched.  To search a different string, the compiled regular expression must be <span class="hardNobr">"set"</span> to the new string.  Therefore, <span class="rkl">RegexKit<i>Lite</i></span> tracks the last <span class="code">NSString</span> that each compiled regular expression was set to, recording the pointer to the <span class="code">NSString</span> object, its hash, and its length.  If any of these parameters are different from the last parameters used for a compiled regular expression, the compiled regular expression is <span class="hardNobr">"set"</span> to the new string.  Since mutating a string will likely change its <span class="code">hash</span> value, it&#39;s generally safe to search <span class="code">NSMutableString</span> objects, and in most cases the mutation will reset the compiled regular expression to the updated contents of the <span class="code">NSMutableString</span>.</p>

<div class="box caution"><div class="table"><div class="row"><div class="label cell">Caution:</div><div class="message cell"><p>Care must be taken when mutable strings are searched and there exists the possibility that the string has mutated between searches.  See <a href="#NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings" class="section-link">NSString <span class="rkl">RegexKit<i>Lite</i></span> Additions Reference - Cached Information and Mutable Strings</a> for more information.</p></div></div></div></div>

<h4>Last Match Information</h4>

<p>When performing a match, the arguments used to perform the match are kept.  If those same arguments are used again, the actual matching operation is skipped because the compiled regular expression already contains the results for the given arguments.  This is mostly useful when a regular expression contains multiple capture groups, and the results for different capture groups for the same match are needed.  This means that there is only a small penalty for iterating over all the capture groups in a regular expression for a match, and essentially becomes the direct ICU regular expression API equivalent of <a href="http://www.icu-project.org/apiref/icu4c/uregex_8h.html#5a2eccd52a16efe1ba99c53d56614a4f" class="code hardNobr">uregex_start()</a> and <a href="http://www.icu-project.org/apiref/icu4c/uregex_8h.html#3f5e9eba75d943ff1aba3d3dc779a67f" class="code hardNobr">uregex_end()</a>.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://www.icu-project.org/apiref/icu4c/uregex_8h.html" class="section-link printURL">ICU4C C API - Regular Expressions</a></li>
    <li><a href="#ICUSyntax_ICURegularExpressionSyntax" class="section-link">ICU Regular Expression Syntax</a></li>
  </ul>
</div>

<h3><span class="code hardNobr">UTF-16</span> Conversion Cache</h3>

<p><span class="rkl">RegexKit<i>Lite</i></span> is ideal when the string being matched is a <span class="hardNobr">non-<span class="code">ASCII</span>,</span> Unicode string.  This is because the regular expression engine used, ICU, can only operate on <span class="code hardNobr">UTF-16</span> encoded strings.  Since Cocoa keeps essentially all <span class="hardNobr">non-<span class="code">ASCII</span></span> strings encoded in <span class="code hardNobr">UTF-16</span> form internally, this means that <span class="rkl">RegexKit<i>Lite</i></span> can operate directly on the strings buffer without having to make a temporary copy and transcode the string in to ICU&#39;s required format.</p>

<p>Like all object oriented programming, the internal representation of an objects information is private.  However, the ICU regular expression engine requires that the text to be search be encoded as a <span class="code hardNobr">UTF-16</span> string.  For pragmatic purposes, <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> has several public functions that can provide direct access to the buffer used to hold the contents of the string, but such direct access is only available if the private buffer is already encoded in the requested direct access format.  As a rough rule of thumb, <span class="hardNobr">8-bit</span> simple strings, such as <span class="code">ASCII</span>, are kept in their <span class="hardNobr">8-bit</span> format.  Non <span class="hardNobr">8-bit</span> simple strings are stored as <span class="code hardNobr">UTF-16</span> strings.  Of course, this is an implementation private detail, so this behavior should never be relied upon.  It is mentioned because of the tremendous impact on matching performance and efficiency it can have if a string must be converted to <span class="hardNobr code">UTF-16</span>.</p>

<p>For strings in which direct access to the <span class="code hardNobr">UTF-16</span> string is available, <span class="rkl">RegexKit<i>Lite</i></span> uses that buffer.  This is the ideal case as no extra work needs to be performed, such as converting the string in to a <span class="code hardNobr">UTF-16</span> string, and allocating memory to hold the temporary conversion.  Of course, direct access is not always available, and occasionally the string to be searched will need to be converted in to a <span class="code hardNobr">UTF-16</span> string.</p>

<p><span class="rkl">RegexKit<i>Lite</i></span> has two conversion cache types. Each conversion cache type contains four buffers each, and buffers are re-used on a least recently used basis.  If the selected cache type does not contain the contents of the <span class="code">NSString</span> that is currently being searched in any of its buffers, the least recently used buffer is cleared and the current <span class="code">NSString</span> takes it place.  The first conversion cache type is fixed in size and set by the <span class="hardNobr">C pre-processor</span> define <span class="cpp_flag">RKL_FIXED_LENGTH</span>, which defaults to <span class="code">2048</span>.  Any string whose length is less than <span class="cpp_flag">RKL_FIXED_LENGTH</span> will use the fixed size conversion cache type.  The second conversion cache type, for strings whose length is longer than <span class="cpp_flag">RKL_FIXED_LENGTH</span>, will use a dynamically sized conversion buffer.  The memory allocation for the dynamically sized conversion buffer is resized for each conversion with <span class="code hardNobr">realloc()</span> to the size needed to hold the entire contents of the <span class="code hardNobr">UTF-16</span> converted string.</p>

<p>This strategy was chosen for its relative simplicity.  Keeping track of dynamically created resources is required to prevent memory leaks.  As designed, there are only four pointers to dynamically allocated memory: the four pointers to hold the conversion contents of strings whose length is larger than <span class="cpp_flag">RKL_FIXED_LENGTH</span>.  However, since <span class="code hardNobr">realloc()</span> is used to manage those memory allocations, it becomes very difficult to accidentally leak the buffers.  Having the fixed sized buffers means that the memory allocation system isn&#39;t bothered with many small requests, most of which are transient in nature to begin with.  The current strategy tries to strike the best balance between performance and simplicity.</p>

<h4>Mutable Strings</h4>

<p>When converted in to a <span class="code hardNobr">UTF-16</span> string, the <span class="code">hash</span> of the <span class="code">NSString</span> is recorded, along with the pointer to the <span class="code">NSString</span> object and the strings length.  In order for the <span class="rkl">RegexKit<i>Lite</i></span> to use the cached conversion, all of these parameters must be equal to their values of the <span class="code">NSString</span> to be searched.  If there is any difference, the cached conversion is discarded and the current <span class="code">NSString</span>, or <span class="code">NSMutableString</span> as the case may be, is reconverted in to a <span class="code hardNobr">UTF-16</span> string.</p>

<div class="box caution"><div class="table"><div class="row"><div class="label cell">Caution:</div><div class="message cell"><p>Care must be taken when mutable strings are searched and there exists the possibility that the string has mutated between searches.  See <a href="#NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings" class="section-link">NSString <span class="rkl">RegexKit<i>Lite</i></span> Additions Reference - Cached Information and Mutable Strings</a> for more information.</p></div></div></div></div>

<h3>Multithreading Safety</h3>

<p><span class="rkl">RegexKit<i>Lite</i></span> is also multithreading safe.  Access to the compiled regular expression cache and the conversion cache is protected by a single <a href="http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man3/spinlock.3.html" class="code">OSSpinLock</a> to ensure that only one thread has access at a time.  The lock remains held while the regular expression match is performed since the compiled regular expression returned by the ICU library is not safe to use from multiple threads.  Once the match has completed, the lock is released, and another thread is free to lock the cache and perform a match.</p>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>While it is safe to use the same regular expression from any thread at any time, the usual multithreading caveats apply.  For example, it is not safe to mutate a <span class="code">NSMutableString</span> in one thread while performing a match on the mutating string in another.</p>
</div></div></div></div>

<p>If Blocks functionality is enabled, and a <span class="rkl">RegexKit<i>Lite</i></span> method that takes a Block as one of its parameters is used, <span class="rkl">RegexKit<i>Lite</i></span> takes a slightly different approach in order to support the asynchronous, and possibly re-entrant, nature of Blocks.</p>

<p>First, an autoreleased Block helper proxy object is created and is used to keep track of any Block local resources needed to perform a Block-based enumeration.</p>

<p>Then the regular expression cache is checked exactly as before. Once a compiled regular expression is obtained, the ICU function <a href="http://icu-project.org/apiref/icu4c/uregex_8h.html#a3befb11b7c9b28c19af6114ed19b7339" class="code">uregex_clone</a> is used to create a Block local copy of the regular expression. After the Block local copy has been made, the global compiled regular expression cache lock is unlocked.</p>

<p>If the string to be searched requires conversion to <span class="hardNobr code">UTF-16</span>, then a one time use Block local <span class="hardNobr code">UTF-16</span> conversion of the string is created.</p>

<p>These changes mean that <span class="rkl">RegexKit<i>Lite</i></span> Block-based enumeration methods are just as multithreading safe and easy to use as non-Block-based enumeration methods, such as the ability to continue to use <span class="rkl">RegexKit<i>Lite</i></span> methods without any restrictions from within the Block used for enumeration.</p>

<h3>64-bit Support</h3>

<p><span class="rkl">RegexKit<i>Lite</i></span> is <span class="hardNobr">64-bit</span> clean.  Internally, <span class="rkl">RegexKit<i>Lite</i></span> uses Cocoas standard <span class="code">NSInteger</span> and <span class="code">NSUInteger</span> types for representing integer values.  The size of these types change between <span class="hardNobr">32-bit</span> and <span class="hardNobr">64-bit</span> automatically, depending on the target architecture.  ICU, on the other hand, uses a signed <span class="hardNobr">32-bit</span> <span class="code">int</span> type for many of its arguments, such as string offset values. Because of this, the maximum length of a string that <span class="rkl">RegexKit<i>Lite</i></span> will accept is the maximum value that can be represented by a signed 32-bit integer, which is approximately 2 gigabytes.  Strings that are longer this limit will raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSRangeException" class="code">NSRangeException</a>. This limitation may be significant to those who are switching to <span class="hardNobr">64-bit</span> because the size of the data they need to process exceeds what can be represented with <span class="hardNobr">32-bits.</span></p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>Several numeric constants throughout this document will have either <span class="code">L</span> or <span class="code">UL</span> appended to them&mdash; for example <span class="code">0UL</span>, or <span class="code">2L</span>.  This is to ensure that they are treated as <span class="hardNobr">64-bit</span> <span class="code">long</span> or <span class="code">unsigned long</span> values, respectively, when targeting a <span class="hardNobr">64-bit</span> architecture.</p>
</div></div></div></div>

</div>

<div class="printPageBreakAfter">
<h2 id="UsingRegexKitLite">Using <span class="rkl">RegexKit<i>Lite</i></span></h2>

<p>The goal of <span class="rkl">RegexKit<i>Lite</i></span> is not to be a comprehensive <span class="hardNobr">Objective-C</span> regular expression framework, but to provide a set of easy to use primitives from which additional functionality can be created.  To this end, <span class="rkl">RegexKit<i>Lite</i></span> provides the following two core primitives from which everything else is built:</p>

<ul class="square highlights">
  <li><span class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">captureCountWithOptions:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></span></li>
  <li><span class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="selector">rangeOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></span></li>
</ul>

<p>There is often a need to create a new string of the characters that were matched by a regular expression.  <span class="rkl">RegexKit<i>Lite</i></span> provides the following method which conveniently combines sending the receiver <span class="code">substringWithRange:</span> with the range returned by <span class="code">rangeOfRegex:</span>.</p>

<ul class="square highlights">
  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByMatching:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div></li>
</ul>

<p><span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 2.0</span> adds the ability to split strings by dividing them with a regular expression, and the ability to perform search and replace operations using common <span class="hardNobr"><span class="regex">$</span><span class="argument">n</span></span> substitution syntax.  <a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" title="Replaces all occurrences of the regular expression regex with the contents of replacement string after performing capture group substitutions, returning the number of replacements made." class="code">replaceOccurrencesOfRegex:withString:</a> is used to modify the contents of <span class="code">NSMutableString</span> objects directly and <a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" title="Returns a string created from the characters of the receiver that are in the range of the first match of regex." class="code">stringByReplacingOccurrencesOfRegex:withString:</a> will create a new, immutable <span class="code">NSString</span> from the receiver.</p>

<ul class="square highlights">
  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div></li>
  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSUInteger">NSUInteger</a>)<span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div></li>
  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div></li>
</ul>

<p><span class="rkl">RegexKit<i>Lite</i></span> 3.0 adds several new methods that return a <span class="code">NSArray</span> containing the aggregated results of a number of individual regex operations.</p>

<ul class="square highlights">
  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">arrayOfCaptureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div></li>
  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">captureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div></li>
  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div></li>
</ul>

<p><span class="rkl">RegexKit<i>Lite</i></span> 4.0 adds several new methods that take advantage of the new blocks language extension.</p>

<ul class="square highlights">
<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)</span><span class="selector">enumerateStringsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span><span class="hardNobr">(void (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>
<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)</span><span class="selector">enumerateStringsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span><span class="hardNobr">(void (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>

<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)</span><span class="selector">enumerateStringsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span><span class="hardNobr">(void (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>
<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)</span><span class="selector">enumerateStringsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span><span class="hardNobr">(void (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>

<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)</span><span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>
<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)</span><span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>

<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSUInteger">NSUInteger</a>)</span><span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>
<li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSUInteger">NSUInteger</a>)</span><span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> (^)</span><span class="hardNobr">(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,</span> <span class="hardNobr"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],</span> <span class="hardNobr">const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],</span> <span class="hardNobr">volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</span></div></li>
</ul>

<p>There are no additional classes that supply the regular expression matching functionality, everything is accomplished with the two methods above.  These methods are added to the existing <span class="code">NSString</span> class via an <span class="hardNobr">Objective-C</span> category extension.  See <a href="#RegexKitLiteNSStringAdditionsReference" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference</a> for a complete list of methods.</p>

<p>The real workhorse is the <a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:" class="code hardNobr">rangeOfRegex:options:inRange:capture:error:</a> method.  The receiver of the message is an ordinary <span class="code">NSString</span> class member that you wish to perform a regular expression match on.  The parameters of the method are a <span class="code">NSString</span> containing the regular expression <span class="argument">regex</span>, any <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> match <span class="argument">options</span>, the <span class="code">NSRange</span> <span class="argument">range</span> of the receiver that is to be searched, the <span class="argument">capture</span> number from the regular expression <span class="argument">regex</span> that you would like the result for, and an optional <span class="argument">error</span> parameter that will contain a <span class="code">NSError</span> object if a problem occurs with the details of the error.</p>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>The <span class="hardNobr">C language</span> assigns special meaning to <span class="hardNobr">the <span class="consoleText">\</span> character</span> when inside a <span class="hardNobr">quoted <span class="consoleText">"&nbsp;"</span> string</span> in your source code.  <span class="hardNobr">The <span class="consoleText">\</span> character</span> is the escape character, and the character that follows has a different meaning than normal.  The most common example of this <span class="hardNobr">is <span class="consoleText">\n</span>,</span> which translates in to the <span class="regex-def">new-line</span> character.  Because of this, you are required to <span class="hardNobr">&#39;escape&#39;</span> any uses <span class="hardNobr">of <span class="consoleText">\</span> by</span> prepending it with <span class="hardNobr">another <span class="consoleText">\</span>.</span>  In practical terms this means doubling <span class="hardNobr">any <span class="consoleText">\</span> in</span> a regular expression, which unfortunately is quite common, that are inside of <span class="hardNobr">quoted <span class="consoleText">"&nbsp;"</span> strings</span> in your source code. Failure to do so will result in numerous warnings from the compiler about unknown escape sequences. To match a single literal <span class="consoleText">\</span> with a regular expression requires no less than four backslashes: <span class="consoleText">&quot;\\\\&quot;</span>.</p>
</div></div></div></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#ICUSyntax_ICURegularExpressionSyntax" class="section-link">ICU Regular Expression Syntax</a></li>
    <li><a href="#RegexKitLiteCookbook" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> Cookbook</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>

<h3>Finding the Range of a Match</h3>

<p>A simple example:</p>

<div class="box sourcecode"><div>NSString *searchString = <span class="hardNobr">@&quot;This is neat.&quot;;</span>
NSString *regexString  = <span class="hardNobr">@&quot;(\\w+)\\s+(\\w+)\\s+(\\w+)&quot;;</span>
NSRange   matchedRange = <span class="hardNobr">NSMakeRange(NSNotFound, 0UL);</span>
NSError  *error        = NULL;

<span class="hardNobr">matchedRange = [searchString</span> <span class="hardNobr">rangeOfRegex:regexString</span> <span class="hardNobr">options:RKLNoOptions</span> <span class="hardNobr">inRange:searchRange</span> <span class="hardNobr">capture:2L</span> <span class="hardNobr">error:&amp;error];</span>

NSLog(@&quot;matchedRange: %@&quot;, NSStringFromRange(matchedRange));
// <span class="comment">2008-03-18 03:51:16.530 test[51583:813] matchedRange: {5, 2}</span></div><div class="metainfo bottom noPrintBorder"><span class="entry continues below"><span class="item meta">Continues&hellip;</span></span></div><div class="floatRightPadder noSelect">&nbsp;</div></div>

<p>In the previous example, the <span class="code">NSRange</span> that capture number <span class="code">2</span> matched is <span class="code hardNobr">{5, 2}</span>, which corresponds to the word <span class="quotedText">is</span> in <span class="code">searchString</span>.  Once the <span class="code">NSRange</span> is known, you can create a new string containing just the matching text:</p>

<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">&hellip;example</span></span></div><div><span class="hardNobr">NSString *matchedString = [searchString</span> <span class="hardNobr">substringWithRange:matchedRange];</span>

NSLog(@&quot;matchedString: &#39;%@&#39;&quot;, matchedString);
// <span class="comment">2008-03-18 03:51:16.532 test[51583:813] matchedString: &#39;is&#39;</span></div></div>

<p><span class="rkl">RegexKit<i>Lite</i></span> can conveniently combine the two steps above with <span class="code">stringByMatching:</span>.  This example also demonstrates the use of one of the simpler convenience methods, where some of the arguments are automatically filled in with default values:</p>

<div class="box sourcecode"><div>NSString *searchString  = <span class="hardNobr">@&quot;This is neat.&quot;;</span>
NSString *regexString   = <span class="hardNobr">@&quot;(\\w+)\\s+(\\w+)\\s+(\\w+)&quot;;</span>

NSString *matchedString = [searchString <span class="hardNobr">stringByMatching:regexString</span> <span class="hardNobr">capture:2L];</span>

NSLog(@&quot;matchedString: &#39;%@&#39;&quot;, matchedString);
// <span class="comment">2008-03-18 03:53:42.949 test[51583:813] matchedString: &#39;is&#39;</span></div></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:" class="code">- rangeOfRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:" class="code">- stringByMatching:</a></li>
    <li><a href="#ICUSyntax_ICURegularExpressionSyntax" class="section-link">ICU Regular Expression Syntax</a></li>
  </ul>
</div>

<h3>Search and Replace</h3>

<p>You can perform search and replace operations on <span class="code">NSString</span> objects and use common <span class="hardNobr"><span class="regex">$</span><span class="argument">n</span></span> capture group substitution in the replacement string:</p>

<div class="box sourcecode">NSString *searchString      = <span class="hardNobr">@&quot;This is neat.&quot;;</span>
NSString *regexString       = <span class="hardNobr">@&quot;\\b(\\w+)\\b&quot;;</span>
NSString *replaceWithString = <span class="hardNobr">@&quot;{$1}&quot;;</span>
NSString *replacedString    = <span class="hardNobr">NULL;</span>

replacedString = <span class="hardNobr">[searchString</span> <span class="hardNobr">stringByReplacingOccurrencesOfRegex:regexString</span> <span class="hardNobr">withString:replaceWithString];</span>

NSLog(@&quot;replaced string: &#39;%@&#39;&quot;, replacedString);
// <span class="comment">2008-07-01 19:03:03.195 test[68775:813] replaced string: &#39;<span class="hardNobr">{This}</span> <span class="hardNobr">{is}</span> <span class="hardNobr">{neat}.&#39;</span></span></div>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Search and replace methods will raise a <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if the <span class="argument">replacementString</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression.</div></div></div></div>

<p>In this example, the regular expression <span class="regex">\b(\w+)\b</span> has a single capture group, which is created with the use of <span class="regex">()</span> parenthesis.  The text that was matched inside the parenthesis is available for use in the replacement text by using <span class="hardNobr"><span class="regex">$</span><span class="argument" title="Decimal Number">n</span></span>, where <span class="argument" title="Decimal Number">n</span> is the parenthesized capture group you would like to use.  Additional capture groups are numbered sequentially in the order that they appear from left to right.  Capture group <span class="consoleText" title="Zero">0</span> (zero) is also available and is equivalent to all the text that the regular expression matched.</p>

<p>Mutable strings can be manipulated directly:</p>

<div class="box sourcecode">NSMutableString *mutableString     <span class="hardNobr">= [NSMutableString</span> <span class="hardNobr">stringWithString:@&quot;This is neat.&quot;];</span>
NSString        *regexString       <span class="hardNobr">= @&quot;\\b(\\w+)\\b&quot;;</span>
NSString        *replaceWithString <span class="hardNobr">= @&quot;{$1}&quot;;</span>
NSUInteger       replacedCount     <span class="hardNobr">= 0UL;</span>

replacedCount = <span class="hardNobr">[mutableString</span> <span class="hardNobr">replaceOccurrencesOfRegex:regexString</span> <span class="hardNobr">withString:replaceWithString];</span>

NSLog(@&quot;count: %lu string: &#39;%@&#39;&quot;, (u_long)replacedCount, mutableString);
// <span class="comment">2008-07-01 21:25:43.433 test[69689:813] <span class="hardNobr">count: 3</span> string: &#39;<span class="hardNobr">{This}</span> <span class="hardNobr">{is}</span> <span class="hardNobr">{neat}.&#39;</span></span></div>

<h4>Search and Replace using Blocks</h4>

<span class="rkl">RegexKit<i>Lite</i></span> 4.0 adds support for performing the same search and replacement on strings, except now the contents of the replacement string are created by the Block that is passed as the argument.  For each match that is found in the string, the Block argument is called and passed the details of the match which includes a C array of <span class="code">NSString</span> objects, one for each capture, along with a C array of <span class="code">NSRange</span> structures with the range information for the current match.

The text that was matched will be replaced with the <span class="code">NSString</span> object that the Block is required to return. %
This allows you complete control over the contents of the replaced text, such as doing complex transformations of the matched text, which is much more flexible and powerful than the simple, fixed replacement functionality provided by <a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" class="code">stringByReplacingOccurrencesOfRegex:withString:</a>.

The example below is essentially the same as the previous search and replace examples, except this example uses the <span class="code">capitalizedString</span> method to capitalize the matched result, which is then used in the string that is returned as the replacement text.  Note that the first letter in each word in <span class="code">replacedString</span> is now capitalized.

<div class="box sourcecode">NSString *searchString      = @&quot;This is neat.&quot;;
NSString *regexString       = @&quot;\\b(\\w+)\\b&quot;;
NSString *replacedString    = NULL;

replacedString = [searchString stringByReplacingOccurrencesOfRegex:regexString
                                                        usingBlock:
                  ^NSString *(NSInteger captureCount,
                              NSString * const capturedStrings,
                              const NSRange capturedRanges[captureCount],
                              volatile BOOL * const stop) {
                    return([NSString stringWithFormat:@&quot;{%@}&quot;,
                            [capturedStrings[1] capitalizedString]]);
                  }];

// 2010-04-14 21:00:42.726 test[35053:a0f] replaced string: &#39;{This} {Is} {Neat}.&#39;</div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:" class="code">- replaceOccurrencesOfRegex:usingBlock:</a></li>
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" class="code">- replaceOccurrencesOfRegex:withString:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:" class="code">- stringByReplacingOccurrencesOfRegex:usingBlock:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" class="code">- stringByReplacingOccurrencesOfRegex:withString:</a></li>
    <li><a href="#ICUSyntax_ICURegularExpressionSyntax" class="section-link">ICU Regular Expression Syntax</a></li>
    <li><a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a></li>
  </ul>
</div>

<h3>Splitting Strings</h3>

<p>Strings can be split with a regular expression using the <a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" title="Returns a NSArray containing substrings of the receiver that have been divided by the regular expression regex." class="code">componentsSeparatedByRegex:</a> methods.  This functionality is nearly identical to the preexisting <span class="code">NSString</span> method <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/componentsSeparatedByString:" class="code hardNobr">componentsSeparatedByString:</a>, except instead of only being able to use a fixed string as a separator, you can use a regular expression:</p>

<div class="box sourcecode"><div>NSString *searchString <span class="hardNobr">= @&quot;This is neat.&quot;;</span>
NSString *regexString  <span class="hardNobr">= @&quot;\\s+&quot;;</span>
NSArray  *splitArray   <span class="hardNobr">= NULL;</span>

splitArray = <span class="hardNobr">[searchString</span> <span class="hardNobr">componentsSeparatedByRegex:regexString];</span>
// <span class="comment">splitArray == { @&quot;This&quot;, @&quot;is&quot;, @&quot;neat.&quot; }</span>

<span class="hardNobr">NSLog(@&quot;splitArray: %@&quot;,</span> <span class="hardNobr">splitArray);</span></div><div class="metainfo bottom noPrintBorder"><span class="entry continues below"><span class="item meta">Continues&hellip;</span></span></div><div class="floatRightPadder noSelect">&nbsp;</div></div>

<p>The output from <span class="code">NSLog()</span> when run from a shell:</p>

<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">&hellip;</span><span class="item info">splitArray</span></span></div><span class="shellOutput">shell% </span><span class="userInput">./splitArray<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">2008-07-01 20:58:39.025 splitArray[69618:813] splitArray: (
    This,
    is,
    &quot;neat.&quot;
)
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>

<p>Unfortunately our example string <span class="code">@&quot;This is neat.&quot;</span> doesn&#39;t allow us to show off the power of regular expressions.  As you can probably imagine, splitting the string with the regular expression <span class="regex">\s+</span> allows for one or more <a href="#ICUSyntax_ICURegularExpressionSyntax_white_space" title="White space is defined as [\t\n\f\r\p{Z}]." class="regex-def">white space</a> characters to be matched.  This can be much more flexible than just a fixed string of <span class="code hardNobr">@&quot;&nbsp;&quot;</span>, which will split on a single space only.  If our example string contained extra spaces, say <span class="code hardNobr">@&quot;This&nbsp;&nbsp;&nbsp;is&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;neat.&quot;</span>, the result would have been the same.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">- componentsSeparatedByRegex:</a></li>
    <li><a href="#ICUSyntax_ICURegularExpressionSyntax" class="section-link">ICU Regular Expression Syntax</a></li>
  </ul>
</div>

<h3>Creating an Array of Every Match</h3>

<p><span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 3.0</span> adds several methods that conveniently perform a number of individual <span class="rkl">RegexKit<i>Lite</i></span> operations and aggregate the results in to a <span class="code">NSArray</span>.  Since the result is a <span class="code">NSArray</span>, the standard Cocoa collection enumeration patterns can be used, such as <span class="code">NSEnumerator</span> and <span class="hardNobr">Objective-C 2.0&#39;s</span> <span class="hardNobr code">for&hellip;in</span> feature.  One of the most common tasks is to extract all of the matches of a regular expression from a string. <span class="code">componentsMatchedByRegex:</span> returns the entire text matched by a regular expression even if the regular expression contains additional capture groups, effectively capture group <span class="code">0</span>. For example:</p>

<div class="box sourcecode"><div>NSString *searchString = <span class="hardNobr">@&quot;$10.23, $1024.42, $3099&quot;;</span>
NSString *regexString  = <span class="hardNobr">@&quot;\\$((\\d+)(?:\\.(\\d+)|\\.?))&quot;;</span>
NSArray  *matchArray   = NULL;

matchArray = [searchString componentsMatchedByRegex:regexString];

// <span class="comment">matchArray == { @&quot;$10.23&quot;, @&quot;$1024.42&quot;, @&quot;$3099&quot; };</span>

<span class="hardNobr">NSLog(@&quot;matchArray: %@&quot;,</span> <span class="hardNobr">matchArray);</span></div><div class="metainfo bottom noPrintBorder"><span class="entry continues below"><span class="item meta">Continues&hellip;</span></span></div><div class="floatRightPadder noSelect">&nbsp;</div></div>

<p>The output from <span class="code">NSLog()</span> when run from a shell:</p>

<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">&hellip;</span><span class="item info">matchArray</span></span></div><span class="shellOutput">shell% </span><span class="userInput">./matchArray<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">2009-05-06 03:20:03.546 matchArray[69939:10b] matchArray: (
    &quot;$10.23&quot;,
    &quot;$1024.42&quot;,
    &quot;$3099&quot;
)
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>


<p>As the example above demonstrates, <span class="code">componentsMatchedByRegex:</span> returns the entire text that the regular expression matched even though the regular expression contains capture groups.  <span class="code">arrayOfCaptureComponentsMatchedByRegex:</span> can be used if you need to get the text that the individual capture groups matched as well:</p>

<div class="box sourcecode"><div>NSString *searchString  = <span class="hardNobr">@&quot;$10.23, $1024.42, $3099&quot;;</span>
NSString *regexString   = <span class="hardNobr">@&quot;\\$((\\d+)(?:\\.(\\d+)|\\.?))&quot;;</span>
NSArray  *capturesArray = NULL;

capturesArray = [searchString arrayOfCaptureComponentsMatchedByRegex:regexString];

/* capturesArray ==
[NSArray arrayWithObjects:
  [NSArray arrayWithObjects:  <span class="hardNobr">@&quot;$10.23&quot;,</span>   <span class="hardNobr">@&quot;10.23&quot;,</span>   <span class="hardNobr">@&quot;10&quot;,</span> <span class="hardNobr">@&quot;23&quot;,</span> <span class="hardNobr">NULL],</span>
  [NSArray arrayWithObjects:<span class="hardNobr">@&quot;$1024.42&quot;,</span> <span class="hardNobr">@&quot;1024.42&quot;,</span> <span class="hardNobr">@&quot;1024&quot;,</span> <span class="hardNobr">@&quot;42&quot;,</span> <span class="hardNobr">NULL],</span>
  [NSArray arrayWithObjects:   <span class="hardNobr">@&quot;$3099&quot;,</span>    <span class="hardNobr">@&quot;3099&quot;,</span> <span class="hardNobr">@&quot;3099&quot;,</span>   <span class="hardNobr">@&quot;&quot;,</span> <span class="hardNobr">NULL],</span>
  NULL];
*/

<span class="hardNobr">NSLog(@&quot;capturesArray: %@&quot;,</span> <span class="hardNobr">capturesArray);</span></div><div class="metainfo bottom noPrintBorder"><span class="entry continues below"><span class="item meta">Continues&hellip;</span></span></div><div class="floatRightPadder noSelect">&nbsp;</div></div>

<p>The output from <span class="code">NSLog()</span> when run from a shell:</p>

<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">&hellip;</span><span class="item info">capturesArray</span></span></div><span class="shellOutput">shell% </span><span class="userInput">./capturesArray<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">2009-05-06 03:25:46.852 capturesArray[69981:10b] capturesArray: (
        (
        &quot;$10.23&quot;,
        &quot;10.23&quot;,
        10,
        23
    ),
        (
        &quot;$1024.42&quot;,
        &quot;1024.42&quot;,
        1024,
        42
    ),
        (
        &quot;$3099&quot;,
        3099,
        3099,
        &quot;&quot;
    )
)
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>


<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:" class="code">- arrayOfCaptureComponentsMatchedByRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:" class="code">- captureComponentsMatchedByRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" class="code">- componentsMatchedByRegex:</a></li>
    <li><a href="#UsingRegexKitLite_EnumeratingMatches" class="section-link">Using <span class="rkl">RegexKit<i>Lite</i></span> - Enumerating Matches</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Collections/Articles/Enumerators.html" class="printURL section-link">Collections Programming Topics for Cocoa - Enumerators: Traversing a Collection&#39;s Elements</a></li>
  </ul>
</div>

<h3 id="UsingRegexKitLite_EnumeratingMatches">Enumerating Matches</h3>

<p>The <span class="rkl">RegexKit<i>Lite</i></span> <span class="code">componentsMatchedByRegex:</span> method enables you to quickly create a <span class="code">NSArray</span> containing all the matches of a regular expression in a string.  To enumerate the contents of the <span class="code">NSArray</span>, you can send the array an <span class="code">objectEnumerator</span> message.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" class="code">- componentsMatchedByRegex:</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html" class="printURL section-link">NSArray Class Reference</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSEnumerator_Class/Reference/Reference.html" class="printURL section-link">NSEnumerator Class Reference</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Collections/Articles/Enumerators.html" class="printURL section-link">Collections Programming Topics for Cocoa - Enumerators: Traversing a Collection&#39;s Elements</a></li>
  </ul>
</div>

<p style="margin-bottom: 0.5em;">An example using <span class="code">componentsMatchedByRegex:</span> and a <span class="code">NSEnumerator</span>:</p>

<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">main.m</span></span></div>#import &lt;Foundation/Foundation.h&gt;
#import &quot;RegexKitLite.h&quot;

int main(int argc, char *argv[]) {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  NSString     *searchString    = @&quot;one\ntwo\n\nfour\n&quot;;
  NSArray      *matchArray      = NULL;
  NSEnumerator *matchEnumerator = NULL;
  NSString     *regexString     = @&quot;(?m)^.*$&quot;;

  NSLog(@&quot;searchString: &#39;%@&#39;&quot;, searchString);
  NSLog(@&quot;regexString : &#39;%@&#39;&quot;, regexString);

  matchArray      = [searchString componentsMatchedByRegex:regexString];
  matchEnumerator = [matchArray objectEnumerator];

  NSUInteger  line          = 0UL;
  NSString   *matchedString = NULL;

  while((matchedString = [matchEnumerator nextObject]) != NULL) {
    NSLog(@&quot;%lu: %lu &#39;%@&#39;&quot;, <span class="hardNobr">(u_long)++line,</span> <span class="hardNobr">(u_long)[matchedString length],</span> <span class="hardNobr">matchedString);</span>
  }

  [pool release];
  return(0);
}</div>

<p id="UsingRegexKitLite_EnumeratingMatches_exampleShellOutput">The following shell transcript demonstrates compiling the example and executing it.  Line number three clearly demonstrates that matches of zero length are possible.  Without the additional logic in <span class="code">nextObject</span> to handle this special case, the enumerator would never advance past the match.</p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>In the shell transcript below, the <span class="code hardNobr">NSLog()</span> line that prints <span class="code">searchString</span> has been annotated with the <span class="hardNobr">&#39;<span class="shellFont">&#9166;</span>&#39;</span> character to help visually identify the corresponding <span class="regex">\n</span> <span class="regex-def">new-line</span> characters in <span class="code">searchString</span>.</p>
</div></div></div></div>

<div class="box shell"><span class="shellOutput">shell% </span><span class="userInput">cd examples<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">shell% </span><span class="userInput">gcc -I.. -g -o main main.m <span class="hardNobr">../RegexKitLite.m</span> <span class="hardNobr">-framework Foundation</span> <span class="hardNobr">-licucore<span class="return" title="Return key">&crarr;</span></span></span>
<span class="shellOutput">shell% </span><span class="userInput">./main<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">2008-03-21 15:56:17.469 main[44050:807] searchString: &#39;one</span><span title="\n in searchString">&#9166;</span><span class="shellOutput">
two</span><span title="\n in searchString">&#9166;</span><span class="shellOutput">&#10;</span><span title="\n in searchString">&#9166;</span><span class="shellOutput">
four</span><span title="\n in searchString">&#9166;</span><span class="shellOutput">
&#39;
2008-03-21 15:56:17.520 main[44050:807] regexString : &#39;<span class="copyAsRegex">(?m)^.*$</span>&#39;
2008-03-21 15:56:17.575 main[44050:807] 1: 3 &#39;one&#39;
2008-03-21 15:56:17.580 main[44050:807] 2: 3 &#39;two&#39;
2008-03-21 15:56:17.584 main[44050:807] 3: 0 &#39;&#39;
2008-03-21 15:56:17.590 main[44050:807] 4: 4 &#39;four&#39;
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>


<h4>Enumerating Matches with Objective-C 2.0</h4>

<p>You can enumerate all the matches of a regular expression in a string using <span class="hardNobr">Objective-C 2.0&#39;s</span> <span class="code hardNobr">for&hellip;in</span> feature.  Compared to using a <span class="code">NSEnumerator</span>, using <span class="code hardNobr">for&hellip;in</span> not only takes fewer lines of code to accomplish the same thing, it is usually faster as well.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/ObjectiveC/Articles/ocFastEnumeration.html" class="printURL section-link">The Objective-C 2.0 Programming Language - Fast Enumeration</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Collections/Articles/Enumerators.html" class="printURL section-link">Collections Programming Topics for Cocoa - Enumerators: Traversing a Collection&#39;s Elements</a></li>
  </ul>
</div>

<p style="margin-bottom: 0.5em;">An example using the <span class="hardNobr">Objective-C 2.0</span> <span class="code hardNobr">for&hellip;in</span> feature:</p>

<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">for_in.m</span></span></div>#import &lt;Foundation/Foundation.h&gt;
#import &quot;RegexKitLite.h&quot;

int main(int argc, char *argv[]) {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  NSString   *searchString = @&quot;one\ntwo\n\nfour\n&quot;;
  NSString   *regexString  = @&quot;(?m)^.*$&quot;;
  NSUInteger  line         = 0UL;

  NSLog(@&quot;searchString: &#39;%@&#39;&quot;, searchString);
  NSLog(@&quot;regexString : &#39;%@&#39;&quot;, regexString);

  for(NSString *matchedString in [searchString <span class="hardNobr">componentsMatchedByRegex:regexString]) {</span>
    NSLog(@&quot;%lu: %lu &#39;%@&#39;&quot;, <span class="hardNobr">(u_long)++line,</span> <span class="hardNobr">(u_long)[matchedString length],</span> <span class="hardNobr">matchedString);</span>
  }

  [pool release];
  return(0);
}</div>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>The output of the preceding example is identical to the <span class="code">NSEnumerator</span> <a href="#UsingRegexKitLite_EnumeratingMatches_exampleShellOutput">shell output</a>.</p>
</div></div></div></div>

<h4>Enumerating Matches using Blocks</h4>

A third way to enumerate all the matches of a regular expression in a string is to use one of the Blocks-based enumeration methods.

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:" class="code">- enumerateStringsMatchedByRegex:usingBlock:</a></li>
    <li><a href="#RegularExpressionEnumerationOptions" class="section-link">Regular Expression Enumeration Options</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>

An example using <span class="code">enumerateStringsMatchedByRegex:usingBlock:</span>:

<!--%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">for\_in.m</span></span></div>-->
<div class="box sourcecode">#import &lt;Foundation/Foundation.h&gt;
#import &quot;RegexKitLite.h&quot;

int main(int argc, char *argv) {
  NSAutoreleasePool  *pool = [[NSAutoreleasePool alloc] init];

          NSString   *searchString = @&quot;one\ntwo\n\nfour\n&quot;;
          NSString   *regexString  = @&quot;(?m)^.*$&quot;;
  __block NSUInteger  line         = 0UL;
  
  NSLog(@&quot;searchString: &#39;%@&#39;&quot;, searchString);
  NSLog(@&quot;regexString : &#39;%@&#39;&quot;, regexString);
  
  [searchString enumerateStringsMatchedByRegex:regexString
                                    usingBlock:
   ^(NSInteger captureCount,
     NSString * const capturedStrings[captureCount],
     const NSRange capturedRanges[captureCount],
     volatile BOOL * const stop) {
     NSLog(@&quot;%lu: %lu &#39;%@&#39;&quot;, ++line, [capturedStrings[0] length], capturedStrings[0]);
   }];

  [pool release];
  return(0);
}</div>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>The output of the preceding example is identical to the <span class="code">NSEnumerator</span> <a href="#UsingRegexKitLite_EnumeratingMatches_exampleShellOutput">shell output</a>.</p>
</div></div></div></div>

<h4 id="UsingRegexKitLite_DTrace">DTrace</h4>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>DTrace support is not enabled by default.  To enable DTrace support, use the <span class="cpp_flag">RKL_DTRACE</span> pre-processor flag: <span class="consoleText">-DRKL_DTRACE</span></p>
</div></div></div></div>

<p><span class="rkl">RegexKit<i>Lite</i></span> has two DTrace probe points that provide information about its internal caches:</p>

<ul class="square highlights">
<li><div class="signature" style="margin-top: 0.5em; margin-bottom: 0.5em;"><span class="hardNobr"><span class="function">RegexKitLite:::compiledRegexCache</span>(</span><span class="hardNobr">unsigned long <span class="argument">eventID</span>,</span> <span class="hardNobr">const char *<span class="argument">regexUTF8</span>,</span> <span class="hardNobr">int <span class="argument">options</span>,</span> <span class="hardNobr">int <span class="argument">captures</span>,</span> <span class="hardNobr">int <span class="argument">hitMiss</span>,</span> <span class="hardNobr">int <span class="argument">icuStatusCode</span>,</span> <span class="hardNobr">const char *<span class="argument">icuErrorMessage</span>,</span> <span class="hardNobr">double *<span class="argument">hitRate</span>);</span></div></li>
<li><div class="signature" style="margin-top: 0.5em; margin-bottom: 0.5em;"><span class="hardNobr"><span class="function">RegexKitLite:::utf16ConversionCache</span>(</span><span class="hardNobr">unsigned long <span class="argument">eventID</span>,</span> <span class="hardNobr">unsigned int <span class="argument">lookupResultFlags</span>,</span> <span class="hardNobr">double *<span class="argument">hitRate</span>,</span> <span class="hardNobr">const void *<span class="argument">string</span>,</span> <span class="hardNobr">unsigned long <span class="argument">NSRange_location</span>,</span> <span class="hardNobr">unsigned long <span class="argument">NSRange_length</span>,</span> <span class="hardNobr">long <span class="argument">length</span>);</span></div></li>
</ul>

<p>Each of the probe points supply information via a number of arguments that are accessible through the DTrace variables <span class="code">arg0</span> &hellip; <span class="code">arg</span><i>n</i>.</p>

<p>The first argument, <span class="argument">eventID</span> via <span class="code">arg0</span>, is a unique event ID that is incremented each time the <span class="rkl">RegexKit<i>Lite</i></span> mutex lock is acquired.  All the probes that fire while the mutex is held will share the same event ID.  This can help if you are trying to correlate multiple events across different CPUs.</p>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell"><p>Most uses of the <span class="consoleText">dtrace</span> command require superuser privileges.  The examples given here use <span class="consoleText">sudo</span> to execute <span class="consoleText">dtrace</span> as the <span class="consoleText">root</span> user.</p></div></div></div></div>

<p>The following is available in <span class="file">examples/compiledRegexCache.d</span> and demonstrates the use of all the arguments available via the <span class="code">RegexKitLite:::compiledRegexCache</span> probe point:</p>

<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">compiledRegexCache.d</span></span></div>#!/usr/sbin/dtrace -s

RegexKitLite*:::compiledRegexCache {
  this-&gt;eventID         = (unsigned long)arg0;
  this-&gt;regexUTF8       = copyinstr(arg1);
  this-&gt;options         = (unsigned int)arg2;
  this-&gt;captures        = (int)arg3;
  this-&gt;hitMiss         = (int)arg4;
  this-&gt;icuStatusCode   = (int)arg5;
  this-&gt;icuErrorMessage = (arg6 == 0) ? &quot;&quot; : copyinstr(arg6);
  this-&gt;hitRate         = (double *)copyin(arg7, sizeof(double));

  printf(&quot;%5d: %-60.60s Opt: %#8.8x Cap: %2d Hit: %2d Rate: %6.2f%% code: %5d msg: %s\n&quot;,
         this-&gt;eventID,
         this-&gt;regexUTF8,
         this-&gt;options,
         this-&gt;captures,
         this-&gt;hitMiss,
         *this-&gt;hitRate,
         this-&gt;icuStatusCode,
         this-&gt;icuErrorMessage);
}</div>

<p>Below is an example of the output, which has been trimmed for brevity, from <span class="file">compiledRegexCache.d</span>:</p>

<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">&hellip;</span><span class="item info">compiledRegexCache.d</span></span></div><span class="shellOutput">shell% </span><span class="userInput">sudo dtrace -Z -q -s compiledRegexCache.d<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">  110: (\[{2})(.+?)(]{2})                                           Opt: 0x00000000 Cap:  3 Hit:  0 Rate:  63.64% code:     0 msg: 
  111: (\[{2})(.+?)(]{2})                                           Opt: 0x00000000 Cap:  3 Hit:  1 Rate:  63.96% code:     0 msg: 
  131: (\w+                                                         Opt: 0x00000000 Cap: -1 Hit: -1 Rate:  63.36% code: 66310 msg: U_REGEX_MISMATCHED_PAREN
  164: \b\s*                                                        Opt: 0x00000000 Cap:  0 Hit:  0 Rate:  60.98% code:     0 msg: 
  165: \$((\d+)(?:\.(\d+)|\.?))                                     Opt: 0x00000000 Cap:  3 Hit:  1 Rate:  61.21% code:     0 msg: 
  166: \b(https?)://([a-zA-Z0-9\-.]+)((?:/[a-zA-Z0-9\-._?,&#39;+\&amp;%$&hellip;   Opt: 0x00000000 Cap:  3 Hit:  0 Rate:  60.84% code:     0 msg: 
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>

<p>An example that prints the number of times that a compiled regular expression was not in the cache per second:</p>

<div class="box shell"><span class="shellOutput">shell% </span><span class="userInput">sudo dtrace -Z -q -n &#39;RegexKitLite*:::compiledRegexCache /arg4 == 0/ { @miss[pid, execname] = count(); }&#39; -n &#39;tick-1sec { printa(&quot;%-8d %-40s %@d/sec\n&quot;, @miss); trunc(@miss); }&#39;<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">67003    RegexKitLite_tests                       16/sec
67008    RegexKitLite_tests                       50/sec</span>
<span class="userInput">^C</span>
<span class="shellOutput">
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#DTrace_RegexKitLiteProbePoints__compiledRegexCache" class="code">RegexKitLite:::compiledRegexCache</a></li>
    <li><a href="http://docs.sun.com/app/docs/doc/817-6223" class="section-link printURL">Solaris Dynamic Tracing Guide</a> <a href="http://dlc.sun.com/pdf/817-6223/817-6223.pdf" class="section-link printURL">(as .PDF)</a></li>
  </ul>
</div>


<p>The following is available in <span class="file">examples/utf16ConversionCache.d</span> and demonstrates the use of all the arguments available via the <span class="code">RegexKitLite:::utf16ConversionCache</span> probe point.</p>

<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">utf16ConversionCache.d</span></span></div>#!/usr/sbin/dtrace -s

enum {
  RKLCacheHitLookupFlag           = 1 &lt;&lt; 0,
  RKLConversionRequiredLookupFlag = 1 &lt;&lt; 1,
  RKLSetTextLookupFlag            = 1 &lt;&lt; 2,
  RKLDynamicBufferLookupFlag      = 1 &lt;&lt; 3,
  RKLErrorLookupFlag              = 1 &lt;&lt; 4
};

RegexKitLite*:::utf16ConversionCache {
  this-&gt;eventID           = (unsigned long)arg0;
  this-&gt;lookupResultFlags = (unsigned int)arg1;
  this-&gt;hitRate           = (double *)copyin(arg2, sizeof(double));
  this-&gt;stringPtr         = (void *)arg3;
  this-&gt;NSRange_location  = (unsigned long)arg4;
  this-&gt;NSRange_length    = (unsigned long)arg5;
  this-&gt;length            = (long)arg6;

  printf(&quot;%5lu: flags: %#8.8x {Hit: %d Conv: %d SetText: %d Dyn: %d Error: %d} rate: %6.2f%% string: %#8.8p NSRange {%6lu, %6lu} length: %ld\n&quot;, 
	 this-&gt;eventID,
	 this-&gt;lookupResultFlags,
	 (this-&gt;lookupResultFlags &amp; RKLCacheHitLookupFlag)           != 0,
	 (this-&gt;lookupResultFlags &amp; RKLConversionRequiredLookupFlag) != 0,
	 (this-&gt;lookupResultFlags &amp; RKLSetTextLookupFlag)            != 0,
	 (this-&gt;lookupResultFlags &amp; RKLDynamicBufferLookupFlag)      != 0,
	 (this-&gt;lookupResultFlags &amp; RKLErrorLookupFlag)              != 0,
	 *this-&gt;hitRate,
	 this-&gt;stringPtr,
	 this-&gt;NSRange_location,
	 this-&gt;NSRange_length,
	 this-&gt;length);
}</div>

<p>Below is an example of the output, which has been trimmed for brevity, from <span class="file">utf16ConversionCache.d</span>:</p>

<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">&hellip;</span><span class="item info">utf16ConversionCache.d</span></span></div><span class="shellOutput">shell% </span><span class="userInput">sudo dtrace -Z -q -s utf16ConversionCache.d<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">   85: flags: 0x00000000 {Hit: 0 Conv: 0 SetText: 0 Dyn: 0 Error: 0} rate:  59.18% string: 0x0010f530 NSRange {     0,     18} length: 18
   86: flags: 0x00000004 {Hit: 0 Conv: 0 SetText: 1 Dyn: 0 Error: 0} rate:  59.18% string: 0x0010f530 NSRange {     0,     18} length: 18
   87: flags: 0x00000006 {Hit: 0 Conv: 1 SetText: 1 Dyn: 0 Error: 0} rate:  58.00% string: 0x00054930 NSRange {     1,     37} length: 39
   88: flags: 0x00000003 {Hit: 1 Conv: 1 SetText: 0 Dyn: 0 Error: 0} rate:  58.82% string: 0x00054930 NSRange {     1,     37} length: 39
  109: flags: 0x00000006 {Hit: 0 Conv: 1 SetText: 1 Dyn: 0 Error: 0} rate:  53.62% string: 0x00054d00 NSRange {     0,     56} length: 56
  110: flags: 0x00000006 {Hit: 0 Conv: 1 SetText: 1 Dyn: 0 Error: 0} rate:  52.86% string: 0x00054680 NSRange {     0,   1064} length: 1064
  111: flags: 0x00000007 {Hit: 1 Conv: 1 SetText: 1 Dyn: 0 Error: 0} rate:  53.52% string: 0x00054680 NSRange {    46,    978} length: 1064
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>

<p>An example that prints the number of times that a string required a conversion to <span class="hardNobr code">UTF-16</span> and was not in the cache per second:</p>

<div class="box shell"><span class="shellOutput">shell% </span><span class="userInput">sudo dtrace -Z -q -n &#39;RegexKitLite*:::utf16ConversionCache /(arg1 &amp; 0x3) == 0x2/ { @miss[pid, execname] = count(); }&#39; -n &#39;tick-1sec { printa(&quot;%-8d %-40s %@d/sec\n&quot;, @miss); trunc(@miss); }&#39;<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">67020    RegexKitLite_tests                       73/sec
67037    RegexKitLite_tests                       64/sec</span>
<span class="userInput">^C</span>
<span class="shellOutput">
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#DTrace_RegexKitLiteProbePoints__utf16ConversionCache" class="code">RegexKitLite:::utf16ConversionCache</a></li>
    <li><a href="#dtrace_utf16ConversionCache_lookupResultFlags" class="section-link">RegexKitLite:::utf16ConversionCache arg1 Flags</a></li>
    <li><a href="http://docs.sun.com/app/docs/doc/817-6223" class="section-link printURL">Solaris Dynamic Tracing Guide</a> <a href="http://dlc.sun.com/pdf/817-6223/817-6223.pdf" class="section-link printURL">(as .PDF)</a></li>
  </ul>
</div>


</div>


<div class="printPageBreakAfter">
<h2 id="ICUSyntax">ICU Syntax</h2>

<p>In this section:</p>

<ul class="overview">
<li><a href="#ICUSyntax_ICURegularExpressionSyntax">ICU Regular Expression Syntax</a></li>
<li><a href="#ICUSyntax_ICURegularExpressionCharacterClasses">ICU Regular Expression Character Classes</a></li>
<li><a href="#ICUSyntax_UnicodeProperties">Unicode Properties</a></li>
<li><a href="#ICUSyntax_ICUReplacementTextSyntax">ICU Replacement Text Syntax</a></li>
</ul>

<h3 id="ICUSyntax_ICURegularExpressionSyntax">ICU Regular Expression Syntax</h3>

<p>For your convenience, the regular expression syntax from the ICU documentation is included below.  When in doubt, you should refer to the official <a href="http://userguide.icu-project.org/strings/regexp" class="section-link NBSP_printURL">ICU User Guide - Regular Expressions</a> documentation page.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://userguide.icu-project.org/strings/regexp" class="section-link printURL">ICU User Guide - Regular Expressions</a></li>
    <li><a href="http://www.unicode.org/reports/tr18/" class="section-link printURL">Unicode Technical Standard #18 - Unicode Regular Expressions</a></li>
  </ul>
</div>


<div class="table regexSyntax"><div class="row"><div class="cell metacharacters">
<table class="regexSyntax" summary="Regular Expression Metacharacters"><caption>Metacharacters</caption>
<tr><th>Character</th><th>Description</th></tr>
<tr><td><span class="regex">\a</span></td><td>Match a <span class="unicodeCharName" title="Unicode Character Name">BELL</span>, <span class="consoleText">\u0007</span></td></tr>
<tr><td><span class="regex">\A</span></td><td>Match at the beginning of the input. Differs from <span class="regex">^</span> in that <span class="regex">\A</span> will not match after a <span class="regex-def">new-line</span> within the input.</td></tr>
<tr><td><span class="regex">\b</span>, outside of a <span class="hardNobr"><span class="regex">[</span><i>Set</i><span class="regex">]</span></span></td>
<td>Match if the current position is a word boundary. Boundaries occur at the transitions between <span class="regex-def">word</span> <span class="regex">\w</span> and <span class="regex-def">non-word</span> <span class="regex">\W</span> characters, with combining marks ignored.<div style="margin-top: 3px; margin-bottom: 2px;"><span class="hardNobr highlight"><b>See also:</b> <a href="#RKLRegexOptions_RKLUnicodeWordBoundaries" class="code">RKLUnicodeWordBoundaries</a></span></div></td></tr>
<tr><td><span class="regex">\b</span>, within a <span class="hardNobr"><span class="regex">[</span><i>Set</i><span class="regex">]</span></span></td><td>Match a <span class="unicodeCharName" title="Unicode Character Name">BACKSPACE</span>, <span class="consoleText">\u0008</span>.</td></tr>
<tr><td><span class="regex">\B</span></td><td>Match if the current position is not a <span class="regex-def">word</span> boundary.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\c</span><i>x</i></span></td><td>Match a <span class="hardNobr"><i title="Control Character x, i.e. ^C">Control-x</i></span> character.</td></tr>
<tr><td><span class="regex">\d</span></td><td>Match any character with the <i>Unicode General Category</i> of <span class="consoleText" title="Unicode Property Name, \p{Nd}">Nd</span> (<i>Number</i>, <i>Decimal Digit</i>).</td></tr>
<tr><td><span class="regex">\D</span></td><td>Match any character that is not a <span class="regex-def">decimal digit</span>.</td></tr>
<tr><td><span class="regex">\e</span></td><td>Match an <span class="unicodeCharName" title="Unicode Character Name">ESCAPE</span>, <span class="consoleText">\u001B</span>.</td></tr>
<tr><td><span class="regex">\E</span></td><td>Terminates a <span class="hardNobr"><span class="regex">\Q</span><span title="Quoted Characters">&hellip;</span><span class="regex">\E</span></span> quoted sequence.</td></tr>
<tr><td><span class="regex">\f</span></td><td>Match a <span class="unicodeCharName" title="Unicode Character Name">FORM FEED</span>, <span class="consoleText">\u000C</span>.</td></tr>
<tr><td><span class="regex">\G</span></td><td>Match if the current position is at the end of the previous match.</td></tr>
<tr><td><span class="regex">\n</span></td><td>Match a <span class="unicodeCharName" title="Unicode Character Name">LINE FEED</span>, <span class="consoleText">\u000A</span>.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\N{</span><i>Unicode Character Name</i><span class="regex">}</span></span></td><td>Match the named <i>Unicode Character</i>.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\p{</span><i>Unicode Property Name</i><span class="regex">}</span></span></td><td>Match any character with the specified <i>Unicode Property</i>.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\P{</span><i>Unicode Property Name</i><span class="regex">}</span></span></td><td>Match any character not having the specified <i>Unicode Property</i>.</td></tr>
<tr><td><span class="regex">\Q</span></td><td>Quotes all following characters until <span class="regex">\E</span>.</td></tr>
<tr><td><span class="regex">\r</span></td><td>Match a <span class="unicodeCharName" title="Unicode Character Name">CARRIAGE RETURN</span>, <span class="consoleText">\u000D</span>.</td></tr>
<tr><td id="ICUSyntax_ICURegularExpressionSyntax_white_space"><span class="regex">\s</span></td><td>Match a <span class="regex-def">white space</span> character. White space is defined as <span class="regex">[\t\n\f\r\p{Z}]</span>.</td></tr>
<tr><td><span class="regex">\S</span></td><td>Match a <span class="hardNobr">non-<span class="regex-def">white space</span></span> character.</td></tr>
<tr><td><span class="regex">\t</span></td><td>Match a <span class="unicodeCharName" title="Unicode Character Name">HORIZONTAL TABULATION</span>, <span class="consoleText">\u0009</span>.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\u</span><i>hhhh</i></span></td><td>Match the character with the hex value <i title="Hexidecimal Number">hhhh</i>.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\U</span><i title="Hexidecimal Number">hhhhhhhh</i></span></td><td>Match the character with the hex value <i title="Hexidecimal Number">hhhhhhhh</i>. Exactly eight hex digits must be provided, even though the largest Unicode code point is <span class="consoleText">\U0010ffff</span>.</td></tr>
<tr><td><span class="regex">\w</span></td><td>Match a word character. Word characters are <span class="regex">[\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}]</span>.</td></tr>
<tr><td><span class="regex">\W</span></td><td>Match a <span class="hardNobr">non-word</span> character.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\x{</span><i title="Hexidecimal Number">h</i>&hellip;<span class="regex">}</span></span></td><td>Match the character with hex value <i title="Hexidecimal Number">hhhh</i>. From one to six hex digits may be supplied.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\x</span><i title="Hexidecimal Number">hh</i></span></td><td>Match the character with two digit hex value <i title="Hexidecimal Number">hh</i>.</td></tr>
<tr><td><span class="regex">\X</span></td><td>Match a <a href="http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries" class="section-link printURL_small">Grapheme Cluster</a>.</td></tr>
<tr><td><span class="regex">\Z</span></td><td>Match if the current position is at the end of input, but before the final line terminator, if one exists.</td></tr>
<tr><td><span class="regex">\z</span></td><td>Match if the current position is at the end of input.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">\</span><i title="Decimal Number">n</i></span></td>
<td>
<div>Back Reference. Match whatever the <i title="Decimal Number">n</i>th capturing group matched. <i title="Decimal Number">n</i> must be a number &ge; 1 and &le; total number of capture groups in the pattern.</div>
<div class="box small"><div><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">Octal escapes, such as <span class="consoleText">\012</span>, are not supported.</div></div></div></div></div>
</td></tr>
<tr><td><span class="hardNobr"><span class="regex">[</span><i>pattern</i><span class="regex">]</span></span></td><td>Match any one character from the set. See <a href="#ICUSyntax_ICURegularExpressionCharacterClasses" class="section-link">ICU Regular Expression Character Classes</a> for a full description of what may appear in the pattern.</td></tr>
<tr><td><span class="regex">.</span></td><td>Match any character.</td></tr>
<tr><td><span class="regex">^</span></td><td>Match at the beginning of a line.</td></tr>
<tr><td><span class="regex">$</span></td><td>Match at the end of a line.</td></tr>
<tr><td><span class="regex">\</span></td><td>Quotes the following character. Characters that must be quoted to be treated as literals are <span class="consoleText">* ? + [ ( ) { } ^ $ | \ . /</span></td></tr>

</table>

</div><div class="cell operators">

<table class="regexSyntax" summary="Regular Expression Operators" id="ICUSyntax_Operators"><caption>Operators</caption>

<tr><th>Operator</th><th>Description</th></tr>
<tr><td><span class="regex">|</span></td><td>Alternation. <span class="regex">A|B</span> matches either <span class="regex">A</span> or <span class="regex">B</span>.</td></tr>
<tr><td><span class="regex">*</span></td><td>Match zero or more times. Match as many times as possible.</td></tr>
<tr><td><span class="regex">+</span></td><td>Match one or more times. Match as many times as possible.</td></tr>
<tr><td><span class="regex">?</span></td><td>Match zero or one times. Prefer one.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">}</span></span></td><td>Match exactly <i title="Decimal Number">n</i> times.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">,}</span></span></td><td>Match at least <i title="Decimal Number">n</i> times. Match as many times as possible.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">,</span><i title="Decimal Number">m</i><span class="regex">}</span></span></td><td>Match between <i title="Decimal Number">n</i> and <i title="Decimal Number">m</i> times. Match as many times as possible, but not more than <i title="Decimal Number">m</i>.</td></tr>
<tr><td><span class="regex">*?</span></td><td>Match zero or more times. Match as few times as possible.</td></tr>
<tr><td><span class="regex">+?</span></td><td>Match one or more times. Match as few times as possible.</td></tr>
<tr><td><span class="regex">??</span></td><td>Match zero or one times. Prefer zero.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">}?</span></span></td><td>Match exactly <i title="Decimal Number">n</i> times.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">,}?</span></span></td><td>Match at least <i title="Decimal Number">n</i> times, but no more than required for an overall pattern match.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">,</span><i title="Decimal Number">m</i><span class="regex">}?</span></span></td><td>Match between <i title="Decimal Number">n</i> and <i title="Decimal Number">m</i> times. Match as few times as possible, but not less than <i title="Decimal Number">n</i>.</td></tr>
<tr><td><span class="regex">*+</span></td><td>Match zero or more times. Match as many times as possible when first encountered, do not retry with fewer even if overall match fails. Possessive match.</td></tr>
<tr><td><span class="regex">++</span></td><td>Match one or more times. Possessive match.</td></tr>
<tr><td><span class="regex">?+</span></td><td>Match zero or one times. Possessive match.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">}+</span></span></td><td>Match exactly <i title="Decimal Number">n</i> times. Possessive match.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">,}+</span></span></td><td>Match at least <i title="Decimal Number">n</i> times. Possessive match.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">{</span><i title="Decimal Number">n</i><span class="regex">,</span><i title="Decimal Number">m</i><span class="regex">}+</span></span></td><td>Match between <i title="Decimal Number">n</i> and <i title="Decimal Number">m</i> times. Possessive match.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td>Capturing parentheses. Range of input that matched the parenthesized subexpression is available after the match.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?:</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td><span class="hardNobr">Non-capturing</span> parentheses. Groups the included pattern, but does not provide capturing of matching text. Somewhat more efficient than capturing parentheses.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?&gt;</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td>Atomic-match parentheses. First match of the parenthesized subexpression is the only one tried; if it does not lead to an overall pattern match, back up the search for a match to a position before the <span class="regex">(?&gt;</span>&nbsp;.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?#</span><span title="Comment">&hellip;</span><span class="regex">)</span></span></td><td>Free-format comment <span class="hardNobr"><span class="regex">(?#</span><i>comment</i><span class="regex">)</span></span>.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?=</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td>Look-ahead assertion. True if the parenthesized pattern matches at the current input position, but does not advance the input position.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?!</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td>Negative look-ahead assertion. True if the parenthesized pattern does not match at the current input position. Does not advance the input position.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?&lt;=</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td>Look-behind assertion. True if the parenthesized pattern matches text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no <span class="regex">*</span> or <span class="regex">+</span> operators).</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?&lt;!</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td>Negative Look-behind assertion. True if the parenthesized pattern does not match text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no <span class="regex">*</span> or <span class="regex">+</span> operators).</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?ismwx-ismwx:</span><span title="Regular Expression">&hellip;</span><span class="regex">)</span></span></td><td>Flag settings. Evaluate the parenthesized expression with the specified flags <i>enabled</i> or <span class="hardNobr"><span class="regex">-</span><i>disabled</i></span>.</td></tr>
<tr><td><span class="hardNobr"><span class="regex">(?ismwx-ismwx)</span></span></td><td>Flag settings. Change the flag settings. Changes apply to the portion of the pattern following the setting. For example, <span class="regex">(?i)</span> changes to a case insensitive match.<div style="margin-top: 2px; margin-bottom: 3px;"><span class="hardNobr highlight"><b>See also:</b> <a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></span></div></td></tr>
</table>

</div></div></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://userguide.icu-project.org/strings/regexp" class="section-link printURL">ICU User Guide - Regular Expressions</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
  </ul>
</div>


  <h3 id="ICUSyntax_ICURegularExpressionCharacterClasses">ICU Regular Expression Character Classes</h3>

  <p>The following was originally from <a href="http://userguide.icu-project.org/strings/unicodeset" class="section-link">ICU User Guide - UnicodeSet</a>, but has been adapted to fit the needs of this documentation.  Specifically, the ICU <span class="code">UnicodeSet</span> documentation describes an ICU C++ object&mdash; <span class="code">UnicodeSet</span>.  The term <span class="code">UnicodeSet</span> was effectively replaced with <b>Character Class</b>, which is more appropriate in the context of regular expressions.  As always, you should refer to the original, official documentation when in doubt.</p>

  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://userguide.icu-project.org/strings/unicodeset" class="section-link printURL">ICU User Guide - UnicodeSet</a></li>
      <li><a href="http://www.unicode.org/reports/tr18/#Subtraction_and_Intersection" class="section-link printURL">UTS #18 Unicode Regular Expressions - Subtraction and Intersection</a></li>
      <li><a href="http://www.unicode.org/reports/tr18/#Categories" class="section-link printURL">UTS #18 Unicode Regular Expressions - Properties</a></li>
    </ul>
  </div>

  <h4>Overview</h4>
  
  <p>A character class is a regular expression pattern that represents a set of Unicode characters or character strings. The following table contains some example character class patterns:</p>

  <table class="regexSyntax">
    <tr><th>Pattern</th><th>Description</th></tr>
    <tr><td><span class="regex">[a-z]</span></td><td>The lower case letters <span class="regexMatch">a</span> through <span class="regexMatch">z</span></td></tr>
    <tr><td><span class="regex">[abc123]</span></td><td>The six characters <span class="regexMatch">a</span>, <span class="regexMatch">b</span>, <span class="regexMatch">c</span>, <span class="regexMatch">1</span>, <span class="regexMatch">2</span>, and <span class="regexMatch">3</span></td></tr>
    <tr><td><span class="regex">[\p{Letter}]</span></td><td>All characters with the Unicode <span class="unicodeProperty">General Category</span> of <span class="unicodeProperty">Letter</span>.</td></tr>
  </table>
  
  <h5>String Values</h5>
  
  <p>In addition to being a set of Unicode code point characters, a character class may also contain string values. Conceptually, a character class is always a set of strings, not a set of characters.  Historically, regular expressions have treated <span class="regex">[</span>&hellip;<span class="regex">]</span> character classes as being composed of single characters only, which is equivalent to a string that contains only a single character.</p>

  <h4>Character Class Patterns</h4>
  
  <p>Patterns are a series of characters bounded by square brackets that contain lists of characters and Unicode property sets. Lists are a sequence of characters that may have ranges indicated by a <span class="regex" title="Hyphen, dash, minus">-</span> between two characters, as in <span class="regex">a-z</span>. The sequence specifies the range of all characters from the left to the right, in Unicode order. For example, <span class="regex">[a c d-f m]</span> is equivalent to <span class="regex">[a c d e f m]</span>. Whitespace can be freely used for clarity as <span class="regex">[a c d-f m]</span> means the same as <span class="regex">[acd-fm]</span>.</p>
  
  <p>Unicode property sets are specified by a Unicode property, such as <span class="regex">[:Letter:]</span>. ICU version 2.0 supports <span class="unicodeProperty">General Category</span>, <span class="unicodeProperty">Script</span>, and <span class="unicodeProperty">Numeric Value</span> properties (ICU will support additional properties in the future). For a list of the property names, see the end of this section. The syntax for specifying the property names is an extension of either POSIX or Perl syntax with the addition of <span class="regex">=value</span>. For example, you can match letters by using the POSIX syntax <span class="regex">[:Letter:]</span>, or by using the Perl syntax <span class="regex">\p{Letter}</span>. The type can be omitted for the <span class="unicodeProperty">Category</span> and <span class="unicodeProperty">Script</span> properties, but is required for other properties.</p>

  <p>The following table lists the standard and negated forms for specifying Unicode properties in both POSIX or Perl syntax. The negated form specifies a character class that includes everything but the specified property. For example, <span class="regex">[:^Letter:]</span> matches all characters that are not <span class="regex">[:Letter:]</span>.</p>

  <table class="regexSyntax">
    <tr><th>Syntax Style</th><th>Standard</th><th>Negated</th></tr>
    <tr><td>POSIX</td><td><span class="regex">[:</span><i>type=value</i><span class="regex">:]</span></td><td><span class="regex">[:^</span><i>type=value</i><span class="regex">:]</span></td></tr>
    <tr><td>Perl</td><td><span class="regex">\p{</span><i>type=value</i><span class="regex">}</span></td><td><span class="regex">\P{</span><i>type=value</i><span class="regex">}</span></td></tr>
  </table>

  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://www.unicode.org/reports/tr18/#Categories" class="section-link printURL">UTS #18 Unicode Regular Expressions - Properties</a></li>
    </ul>
  </div>

  <p>Character classes can then be modified using standard set operations&mdash; Union, Inverse, Difference, and Intersection.</p>

  <ul class="square">
    <li><p>To union two sets, simply concatenate them. For example, <span class="regex">[[:letter:] [:number:]]</span></p></li>
    <li><p>To intersect two sets, use the <span class="regex">&amp;</span> operator. For example, <span class="regex">[[:letter:] &amp; [a-z]]</span></p></li>
    <li><p>To take the set-difference of two sets, use the <span class="regex" title="Hyphen, dash, minus">-</span> operator. For example, <span class="regex">[[:letter:] - [a-z]]</span></p></li>
    <li><p>To invert a set, place a <span class="regex" title="Caret, circumflex">^</span> immediately after the opening <span class="regex">[</span>. For example, <span class="regex">[^a-z]</span>. In any other location, the <span class="regex" title="Caret, circumflex">^</span> does not have a special meaning.</p></li>
  </ul>
  
  <p>The binary operators <span class="regex">&amp;</span> and <span class="regex" title="Hyphen, dash, minus">-</span> have equal precedence and bind left-to-right. Thus <span class="regex">[[:letter:]-[a-z]-[\u0100-\u01FF]]</span> is equivalent to <span class="regex">[[[:letter:]-[a-z]]-[\u0100-\u01FF]]</span>. Another example is the set <span class="regex">[[ace][bdf] - [abc][def]]</span> is <b>not</b> the empty set, but instead the set <span class="regex">[def]</span>. This only really matters for the difference operation, as the intersection operation is commutative.</p>
  
  <p>Another caveat with the <span class="regex">&amp;</span> and <span class="regex" title="Hyphen, dash, minus">-</span> operators is that they operate between <b>sets</b>. That is, they must be immediately preceded and immediately followed by a set. For example, the pattern <span class="regex">[[:Lu:]-A]</span> is illegal, since it is interpreted as the set <span class="regex">[:Lu:]</span> followed by the incomplete range <span class="regex">-A</span>. To specify the set of uppercase letters except for <span class="regex">A</span>, enclose the <span class="regex">A</span> in a set: <span class="regex">[[:Lu:]-[A]]</span>.</p>
  
  <table class="regexSyntax">
    <tr><th>Pattern</th><th>Description</th></tr>
    <tr><td><span class="regex">[a]</span></td><td>The set containing <span class="regexMatch">a</span>.</td></tr>
    <tr><td><span class="regex">[a-z]</span></td><td>The set containing <span class="regexMatch">a</span> through <span class="regexMatch">z</span> and all letters in between, in Unicode order.</td></tr>
    <tr><td><span class="regex">[^a-z]</span></td><td>The set containing all characters but <span class="regexMatch">a</span> through <span class="regexMatch">z</span>, that is, <span class="code">U+0000</span> through <span class="code">a-1</span> and <span class="code">z+1</span> through <span class="code">U+FFFF</span>.</td></tr>
    <tr><td><span class="regex">[[</span><i>pat1</i><span class="regex">][</span><i>pat2</i><span class="regex">]]</span></td><td>The union of sets specified by <i>pat1</i> and <i>pat2</i>.</td></tr>
    <tr><td><span class="regex">[[</span><i>pat1</i><span class="regex">]&amp;[</span><i>pat2</i><span class="regex">]]</span></td><td>The intersection of sets specified by <i>pat1</i> and <i>pat2</i>.</td></tr>
    <tr><td><span class="regex">[[</span><i>pat1</i><span class="regex">]-[</span><i>pat2</i><span class="regex">]]</span></td><td>The asymmetric difference of sets specified by <i>pat1</i> and <i>pat2</i>.</td></tr>
    <tr><td><span class="regex">[:Lu:]</span></td><td>The set of characters belonging to the given Unicode category.  In this case, Unicode uppercase letters. The long form for this is <span class="regex">[:UppercaseLetter:]</span>.</td></tr>
    <tr><td><span class="regex">[:L:]</span></td><td>The set of characters belonging to all Unicode categories starting with <span class="unicodeProperty">L</span>, that is, <span class="regex">[[:Lu:][:Ll:][:Lt:][:Lm:][:Lo:]]</span>. The long form for this is <span class="regex">[:Letter:]</span>.</td></tr>
  </table>

  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://www.unicode.org/reports/tr18/#Subtraction_and_Intersection" class="section-link printURL">UTS #18 Unicode Regular Expressions - Subtraction and Intersection</a></li>
    </ul>
  </div>

  <h5>String Values in Character Classes</h5>
  
  <p>String values are enclosed in <span class="regex">{</span><i>curly brackets</i><span class="regex">}</span>.  For example:</p>
  
  <table class="regexSyntax">
    <tr><th>Pattern</th><th>Description</th></tr>
    <tr><td><span class="regex">[abc{def}]</span></td><td>A set containing four members, the single characters <span class="regexMatch">a</span>, <span class="regexMatch">b</span>, and <span class="regexMatch">c</span> and the string <span class="regexMatch">def</span></td></tr>
    <tr><td><span class="regex">[{abc}{def}]</span></td><td>A set containing two members, the string <span class="regexMatch">abc</span> and the string <span class="regexMatch">def</span>.</td></tr>
    <tr><td><span class="regex">[{a}{b}{c}][abc]</span></td><td>These two sets are equivalent. Each contains three items, the three individual characters <span class="regexMatch">a</span>, <span class="regexMatch">b</span>, and <span class="regexMatch">c</span>. A <span class="regex">{</span><i>string</i><span class="regex">}</span> containing a single character is equivalent to that same character specified in any other way.</td></tr>
  </table>
  
  <h4>Character Quoting and Escaping in ICU Character Class Patterns</h4>
  
  <h5>Single Quote</h5>

  <p>Two single quotes represent a single quote, either inside or outside single quotes. Text within single quotes is not interpreted in any way, except for two adjacent single quotes. It is taken as literal text&mdash; special characters become non-special. These quoting conventions for ICU character classes differ from those of Perl or Java. In those environments, single quotes have no special meaning, and are treated like any other literal character.</p>

  <h5>Backslash Escapes</h5>
  
  <p>Outside of single quotes, certain backslashed characters have special meaning:</p>
  
  <table class="regexSyntax">
    <tr><th>Pattern</th><th>Description</th></tr>
    <tr><td><span class="regex">\u</span><i title="Hexidecimal Number">hhhh</i></td><td>Exactly 4 hex digits; <i>h</i> in <span class="regex">[0-9A-Fa-f]</span></td></tr>
    <tr><td><span class="regex">\U</span><i title="Hexidecimal Number">hhhhhhhh</i></td><td>Exactly 8 hex digits</td></tr>
    <tr><td><span class="regex">\x</span><i title="Hexidecimal Number">hh</i></td><td>1-2 hex digits</td></tr>
    <tr><td><span class="regex">\</span><i>ooo</i></td><td>1-3 octal digits; <i>o</i> in <span class="regex">[0-7]</span></td></tr>
    <tr><td><span class="regex">\a</span></td><td><span class="code">U+0007</span> <span class="unicodeCharName" title="Unicode Character Name">BELL</span></td></tr>
    <tr><td><span class="regex">\b</span></td><td><span class="code">U+0008</span> <span class="unicodeCharName" title="Unicode Character Name">BACKSPACE</span></td></tr>
    <tr><td><span class="regex">\t</span></td><td><span class="code">U+0009</span> <span class="unicodeCharName" title="Unicode Character Name">HORIZONTAL TAB</span></td></tr>
    <tr><td><span class="regex">\n</span></td><td><span class="code">U+000A</span> <span class="unicodeCharName" title="Unicode Character Name">LINE FEED</span></td></tr>
    <tr><td><span class="regex">\v</span></td><td><span class="code">U+000B</span> <span class="unicodeCharName" title="Unicode Character Name">VERTICAL TAB</span></td></tr>
    <tr><td><span class="regex">\f</span></td><td><span class="code">U+000C</span> <span class="unicodeCharName" title="Unicode Character Name">FORM FEED</span></td></tr>
    <tr><td><span class="regex">\r</span></td><td><span class="code">U+000D</span> <span class="unicodeCharName" title="Unicode Character Name">CARRIAGE RETURN</span></td></tr>
    <tr><td><span class="regex">\\</span></td><td><span class="code">U+005C</span> <span class="unicodeCharName" title="Unicode Character Name">BACKSLASH</span></td></tr>
  </table>
  
  <p>Anything else following a backslash is mapped to itself, except in an environment where it is defined to have some special meaning. For example, <span class="regex">\p{Lu}</span> is the set of uppercase letters. Any character formed as the result of a backslash escape loses any special meaning and is treated as a literal. In particular, note that <span class="regex">\u</span> and <span class="regex">\U</span> escapes create literal characters.</p>
  
  <h5>Whitespace</h5>

  <p>Whitespace, as defined by the ICU API, is ignored unless it is quoted or backslashed.</p>
    
  <h4>Property Values</h4>
  
  <p>The following property value styles are recognized:</p>

  <table class="regexSyntax">
    <tr><th>Style</th><th>Description</th></tr>
    <tr><td>Short</td><td>Omits the <span class="regex doNotEscape">=type</span> argument. Used to prevent ambiguity and only allowed with the <span class="unicodeProperty">Category</span> and <span class="unicodeProperty">Script</span> properties.</td></tr>
    <tr><td>Medium</td><td>Uses an abbreviated <span class="regex doNotEscape">type</span> and <span class="regex doNotEscape">value</span>.</td></tr>
    <tr><td>Long</td><td>Uses a full <span class="regex doNotEscape">type</span> and <span class="regex doNotEscape">value</span>.</td></tr>
  </table>
  
  <p>If the <span class="regex doNotCopy">type</span> or <span class="regex doNotCopy">value</span> is omitted, then the <span class="regex doNotCopy">=</span> equals sign is also omitted. The short style is only used for <span class="unicodeProperty">Category</span> and <span class="unicodeProperty">Script</span> properties because these properties are very common and their omission is unambiguous.</p>
  
  <p>In actual practice, you can mix <span class="regex doNotCopy">type</span> names and <span class="regex doNotCopy">values</span> that are omitted, abbreviated, or full. For example, if <span class="unicodeProperty">Category=Unassigned</span> you could use what is in the table explicitly, <span class="regex">\p{gc=Unassigned}</span>, <span class="regex">\p{Category=Cn}</span>, or <span class="regex">\p{Unassigned}</span>.</p>
  
  <p>When these are processed, case and whitespace are ignored so you may use them for clarity, if desired. For example, <span class="regex">\p{Category = Uppercase Letter}</span> or <span class="regex">\p{Category = uppercase letter}</span>.</p>
  
  <p>For a list of properties supported by ICU, see <a href="http://userguide.icu-project.org/strings/properties" class="section-link printURL">ICU User Guide - Unicode Properties</a>.</p>

  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://userguide.icu-project.org/strings/properties" class="section-link printURL">ICU User Guide - Unicode Properties</a></li>
      <li><a href="http://www.unicode.org/reports/tr18/#Categories" class="section-link printURL">UTS #18 Unicode Regular Expressions - Properties</a></li>
    </ul>
  </div>

<h3 id="ICUSyntax_UnicodeProperties">Unicode Properties</h3>

<p>The following tables list some of the commonly used Unicode Properties, which can be matched in a regular expression with <span class="regex">\p{</span><i>Property</i><span class="regex">}</span>. The tables were created from the <a href="http://www.unicode.org/versions/Unicode5.2.0/" class="hardNobr">Unicode 5.2</a> Unicode Character Database, which is the version used by ICU that ships with <span class="hardNobr">Mac OS X 10.6</span>.</p>

<div class="table" style="margin-top: 1em; margin-bottom: 1em;"><div class="row"><div class="cell">

      <table class="regexSyntax unicodeProperties">
	<tr><th colspan="2">Category</th></tr>
	<tr><td class="consoleText">L</td><td class="consoleText">Letter</td></tr>
	<tr><td class="consoleText">LC</td><td class="consoleText">CasedLetter</td></tr>
	<tr><td class="consoleText">Lu</td><td class="consoleText">UppercaseLetter</td></tr>
	<tr><td class="consoleText">Ll</td><td class="consoleText">LowercaseLetter</td></tr>
	<tr><td class="consoleText">Lt</td><td class="consoleText">TitlecaseLetter</td></tr>
	<tr><td class="consoleText">Lm</td><td class="consoleText">ModifierLetter</td></tr>
	<tr><td class="consoleText">Lo</td><td class="consoleText">OtherLetter</td></tr>
	<tr><td class="consoleText" colspan="2">&nbsp;</td></tr>
	<tr><td class="consoleText">P</td><td class="consoleText">Punctuation</td></tr>
	<tr><td class="consoleText">Pc</td><td class="consoleText">ConnectorPunctuation</td></tr>
	<tr><td class="consoleText">Pd</td><td class="consoleText">DashPunctuation</td></tr>
	<tr><td class="consoleText">Ps</td><td class="consoleText">OpenPunctuation</td></tr>
	<tr><td class="consoleText">Pe</td><td class="consoleText">ClosePunctuation</td></tr>
	<tr><td class="consoleText">Pi</td><td class="consoleText">InitialPunctuation</td></tr>
	<tr><td class="consoleText">Pf</td><td class="consoleText">FinalPunctuation</td></tr>
	<tr><td class="consoleText">Po</td><td class="consoleText">OtherPunctuation</td></tr>
	<tr><td class="consoleText" colspan="2">&nbsp;</td></tr>
	<tr><td class="consoleText">N</td><td class="consoleText">Number</td></tr>
	<tr><td class="consoleText">Nd</td><td class="consoleText">DecimalNumber</td></tr>
	<tr><td class="consoleText">Nl</td><td class="consoleText">LetterNumber</td></tr>
	<tr><td class="consoleText">No</td><td class="consoleText">OtherNumber</td></tr>
	<tr><td class="consoleText" colspan="2">&nbsp;</td></tr>
	<tr><td class="consoleText">M</td><td class="consoleText">Mark</td></tr>
	<tr><td class="consoleText">Mn</td><td class="consoleText">NonspacingMark</td></tr>
	<tr><td class="consoleText">Mc</td><td class="consoleText">SpacingMark</td></tr>
	<tr><td class="consoleText">Me</td><td class="consoleText">EnclosingMark</td></tr>
	<tr><td class="consoleText" colspan="2">&nbsp;</td></tr>
	<tr><td class="consoleText">S</td><td class="consoleText">Symbol</td></tr>
	<tr><td class="consoleText">Sm</td><td class="consoleText">MathSymbol</td></tr>
	<tr><td class="consoleText">Sc</td><td class="consoleText">CurrencySymbol</td></tr>
	<tr><td class="consoleText">Sk</td><td class="consoleText">ModifierSymbol</td></tr>
	<tr><td class="consoleText">So</td><td class="consoleText">OtherSymbol</td></tr>
	<tr><td class="consoleText" colspan="2">&nbsp;</td></tr>
	<tr><td class="consoleText">Z</td><td class="consoleText">Separator</td></tr>
	<tr><td class="consoleText">Zs</td><td class="consoleText">SpaceSeparator</td></tr>
	<tr><td class="consoleText">Zl</td><td class="consoleText">LineSeparator</td></tr>
	<tr><td class="consoleText">Zp</td><td class="consoleText">ParagraphSeparator</td></tr>
	<tr><td class="consoleText" colspan="2">&nbsp;</td></tr>
	<tr><td class="consoleText">C</td><td class="consoleText">Other</td></tr>
	<tr><td class="consoleText">Cc</td><td class="consoleText">Control</td></tr>
	<tr><td class="consoleText">Cf</td><td class="consoleText">Format</td></tr>
	<tr><td class="consoleText">Cs</td><td class="consoleText">Surrogate</td></tr>
	<tr><td class="consoleText">Co</td><td class="consoleText">PrivateUse</td></tr>
	<tr><td class="consoleText">Cn</td><td class="consoleText">Unassigned</td></tr>
      </table>

    </div><div class="cell" style="max-width: 4.2in">


      <table class="regexSyntax unicodeProperties" style="width: 100%;">
	<tr><th colspan="3">Script</th></tr>
	<tr><td class="consoleText" style="width: 33%;">Arabic</td><td class="consoleText" style="width: 33%;">Armenian</td><td class="consoleText" style="width: 33%;">Balinese</td></tr>
	<tr><td class="consoleText">Bengali</td><td class="consoleText">Bopomofo</td><td class="consoleText">Braille</td></tr>
	<tr><td class="consoleText">Buginese</td><td class="consoleText">Buhid</td><td class="consoleText softNobr"><span><span class="tbrOn">Canadian_&#8203;Aboriginal</span><span class="tbrOff">Canadian_Aboriginal</span></span></td></tr>
	<tr><td class="consoleText">Carian</td><td class="consoleText">Cham</td><td class="consoleText">Cherokee</td></tr>
	<tr><td class="consoleText">Common</td><td class="consoleText">Coptic</td><td class="consoleText">Cuneiform</td></tr>
	<tr><td class="consoleText">Cypriot</td><td class="consoleText">Cyrillic</td><td class="consoleText">Deseret</td></tr>
	<tr><td class="consoleText">Devanagari</td><td class="consoleText">Ethiopic</td><td class="consoleText">Georgian</td></tr>
	<tr><td class="consoleText">Glagolitic</td><td class="consoleText">Gothic</td><td class="consoleText">Greek</td></tr>
	<tr><td class="consoleText">Gujarati</td><td class="consoleText">Gurmukhi</td><td class="consoleText">Han</td></tr>
	<tr><td class="consoleText">Hangul</td><td class="consoleText">Hanunoo</td><td class="consoleText">Hebrew</td></tr>
	<tr><td class="consoleText">Hiragana</td><td class="consoleText">Inherited</td><td class="consoleText">Kannada</td></tr>
	<tr><td class="consoleText">Katakana</td><td class="consoleText">Kayah_Li</td><td class="consoleText">Kharoshthi</td></tr>
	<tr><td class="consoleText">Khmer</td><td class="consoleText">Lao</td><td class="consoleText">Latin</td></tr>
	<tr><td class="consoleText">Lepcha</td><td class="consoleText">Limbu</td><td class="consoleText">Linear_B</td></tr>
	<tr><td class="consoleText">Lycian</td><td class="consoleText">Lydian</td><td class="consoleText">Malayalam</td></tr>
	<tr><td class="consoleText">Mongolian</td><td class="consoleText">Myanmar</td><td class="consoleText">New_Tai_Lue</td></tr>
	<tr><td class="consoleText">Nko</td><td class="consoleText">Ogham</td><td class="consoleText">Ol_Chiki</td></tr>
	<tr><td class="consoleText">Old_Italic</td><td class="consoleText">Old_Persian</td><td class="consoleText">Oriya</td></tr>
	<tr><td class="consoleText">Osmanya</td><td class="consoleText">Phags_Pa</td><td class="consoleText">Phoenician</td></tr>
	<tr><td class="consoleText">Rejang</td><td class="consoleText">Runic</td><td class="consoleText">Saurashtra</td></tr>
	<tr><td class="consoleText">Shavian</td><td class="consoleText">Sinhala</td><td class="consoleText">Sundanese</td></tr>
	<tr><td class="consoleText">Syloti_Nagri</td><td class="consoleText">Syriac</td><td class="consoleText">Tagalog</td></tr>
	<tr><td class="consoleText">Tagbanwa</td><td class="consoleText">Tai_Le</td><td class="consoleText">Tamil</td></tr>
	<tr><td class="consoleText">Telugu</td><td class="consoleText">Thaana</td><td class="consoleText">Thai</td></tr>
	<tr><td class="consoleText">Tibetan</td><td class="consoleText">Tifinagh</td><td class="consoleText">Ugaritic</td></tr>
	<tr><td class="consoleText">Unknown</td><td class="consoleText">Vai</td><td class="consoleText">Yi</td></tr>
      </table>

      <table class="regexSyntax unicodeProperties" style="margin-top: 2em; width: 100%;">
	<tr><th colspan="2">Extended Property Class</th></tr>
	<tr><td class="consoleText">ASCII_Hex_Digit</td><td class="consoleText">Alphabetic</td></tr>
	<tr><td class="consoleText">Bidi_Control</td><td class="consoleText">Dash</td></tr>
	<tr><td class="consoleText softNobr"><span><span class="tbrOn">Default_&#8203;Ignorable_&#8203;Code_&#8203;Point</span><span class="tbrOff">Default_Ignorable_Code_Point</span></span></td><td class="consoleText">Deprecated</td></tr>
	<tr><td class="consoleText">Diacritic</td><td class="consoleText">Extender</td></tr>
	<tr><td class="consoleText">Grapheme_Base</td><td class="consoleText">Grapheme_Extend</td></tr>
	<tr><td class="consoleText">Grapheme_Link</td><td class="consoleText">Hex_Digit</td></tr>
	<tr><td class="consoleText">Hyphen</td><td class="consoleText softNobr"><span><span class="tbrOn">IDS_&#8203;Binary_&#8203;Operator</span><span class="tbrOff">IDS_Binary_Operator</span></span></td></tr>
	<tr><td class="consoleText">IDS_Trinary_Operator</td><td class="consoleText">ID_Continue</td></tr>
	<tr><td class="consoleText">ID_Start</td><td class="consoleText">Ideographic</td></tr>
	<tr><td class="consoleText">Join_Control</td><td class="consoleText softNobr"><span><span class="tbrOn">Logical_&#8203;Order_&#8203;Exception</span><span class="tbrOff">Logical_Order_Exception</span></span></td></tr>
	<tr><td class="consoleText">Lowercase</td><td class="consoleText">Math</td></tr>
	<tr><td class="consoleText">Noncharacter_Code_Point</td><td class="consoleText">Other_Alphabetic</td></tr>
	<tr><td class="consoleText softNobr"><span><span class="tbrOn">Other_&#8203;Default_&#8203;Ignorable_&#8203;Code_&#8203;Point</span><span class="tbrOff">Other_Default_Ignorable_Code_Point</span></span></td><td class="consoleText softNobr"><span><span class="tbrOn">Other_&#8203;Grapheme_&#8203;Extend</span><span class="tbrOff">Other_Grapheme_Extend</span></span></td></tr>
	<tr><td class="consoleText">Other_ID_Continue</td><td class="consoleText">Other_ID_Start</td></tr>
	<tr><td class="consoleText">Other_Lowercase</td><td class="consoleText">Other_Math</td></tr>
	<tr><td class="consoleText">Other_Uppercase</td><td class="consoleText">Pattern_Syntax</td></tr>
	<tr><td class="consoleText">Pattern_White_Space</td><td class="consoleText">Quotation_Mark</td></tr>
	<tr><td class="consoleText">Radical</td><td class="consoleText">STerm</td></tr>
	<tr><td class="consoleText">Soft_Dotted</td><td class="consoleText softNobr"><span><span class="tbrOn">Terminal_&#8203;Punctuation</span><span class="tbrOff">Terminal_Punctuation</span></span></td></tr>
	<tr><td class="consoleText">Unified_Ideograph</td><td class="consoleText">Uppercase</td></tr>
	<tr><td class="consoleText">Variation_Selector</td><td class="consoleText">White_Space</td></tr>
	<tr><td class="consoleText">XID_Continue</td><td class="consoleText">XID_Start</td></tr>
      </table>
      
</div></div></div>

<h4>Unicode Character Database</h4>

<p>Unicode properties are defined in the <a href="http://www.unicode.org/ucd/">Unicode Character Database</a>, or <span class="new-term">UCD</span>.
From time to time the UCD is <a href="http://www.unicode.org/versions/">revised and updated</a>. The properties available, and the definition of the characters they match, depend on the UCD that ICU was built with.</p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>In general, the ICU and UCD versions change with each major operating system release.</p>
</div></div></div></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://www.unicode.org/reports/tr18/#Categories" class="section-link printURL">UTS #18 Unicode Regular Expressions - Properties</a></li>
    <li><a href="http://www.unicode.org/reports/tr18/#Compatibility_Properties" class="section-link printURL">UTS #18 Unicode Regular Expressions - Compatibility Properties</a></li>
    <li><a href="http://www.unicode.org/ucd/" class="section-link printURL">Unicode Character Database</a></li>
    <li><a href="http://www.unicode.org/versions/Unicode5.2.0/" class="section-link printURL">The Unicode Standard - Unicode 5.2</a></li>
    <li><a href="http://www.unicode.org/versions/" class="section-link printURL">Versions of the Unicode Standard</a></li>
  </ul>
</div>


<h3 id="ICUSyntax_ICUReplacementTextSyntax">ICU Replacement Text Syntax</h3>

<div class="table regexSyntax">
<table class="regexSyntax" summary="Replacement Text Syntax"><caption>Replacement Text Syntax</caption>
<tr><th>Character</th><th>Description</th></tr>
<tr><td><span class="regex">$</span><i title="Decimal Number">n</i></td><td><div>The text of capture group <i title="Decimal Number">n</i> will be substituted for <span class="regex">$</span><i title="Decimal Number">n</i>.  <i title="Decimal Number">n</i> must be &ge; <span class="consoleText">0</span> and not greater than the number of capture groups.  A <span class="regex">$</span> not followed by a digit has no special meaning, and will appear in the substitution text as itself, a <span class="regex">$</span>.</div>
<div class="box small"><div><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Methods will raise a <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <i title="Decimal Number">n</i> is greater than the number of capture groups in the regular expression.</div></div></div></div></div>
</td></tr>
<tr><td><span class="regex">\</span></td><td>Treat the character following the backslash as a literal, suppressing any special meaning.  Backslash escaping in substitution text is only required for <span class="regex">$</span> and <span class="regex">\</span>, but may proceed any character.  The backslash itself will not be copied to the substitution text.</td></tr>
</table>
</div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://userguide.icu-project.org/strings/regexp#TOC-Replacement-Text" class="section-link printURL">ICU User Guide - Replacement Text</a></li>
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:" class="code">- replaceOccurrencesOfRegex:withString:options:range:error:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:" class="code">- stringByReplacingOccurrencesOfRegex:withString:options:range:error:</a></li>
  </ul>
</div>

</div>

<div class="printPageBreakAfter">
  <h2 id="RegexKitLiteCookbook"><span class="rkl">RegexKit<i>Lite</i></span> Cookbook</h2>

  <table class="quotation">
    <tr><td class="quote">Some people, when confronted with a problem, think &ldquo;I know, I&#39;ll use regular expressions.&rdquo; Now they have two problems.</td></tr>
    <tr><td class="attribution">Jamie Zawinski</td></tr>
  </table>

  <p>This section contains a collection of regular expressions and example code demonstrating how <span class="rkl">RegexKit<i>Lite</i></span> makes some common programming choirs easier. <span class="rkl">RegexKit<i>Lite</i></span> makes it easy to match part of a string and extract just that part, or even create an entirely new string using just a few pieces of the original string.  A great example of this is a string that contains a URL and you need to extract just a part of it, perhaps the host or maybe just the port used.  This example demonstrates how easy it is to extract the port used from a URL, which is then converted in to a <span class="code">NSInteger</span> value:</p>

<div class="box sourcecode">searchString = @&quot;http://www.example.com:8080/index.html&quot;;
regexString  = @&quot;\\bhttps?://[a-zA-Z0-9\\-.]+(?::(\\d+))?(?:(?:/[a-zA-Z0-9\\-._?,&#39;+\\&amp;%$=~*!():@\\\\]*)+)?&quot;;

NSInteger portInteger = [[searchString stringByMatching:regexString capture:1L] integerValue];

NSLog(@&quot;portInteger: &#39;%ld&#39;&quot;, (long)portInteger);
// <span class="comment">2008-10-15 08:52:52.500 host_port[8021:807] portInteger: &#39;8080&#39;</span></div>

<p>Inside you&#39;ll find more examples like this that you can use as the starting point for your own regular expression pattern matching solution. Keep in mind that these are meant to be examples to help get you started and not necessarily the ideal solution for every need. Trade&#8209;offs are usually made when creating a regular expression, matching an email address is a perfect example of this.  A regular expression that precisely matches the formal definition of email address is both complicated and usually unnecessary.  Knowing which trade&#8209;offs are acceptable requires that you understand what it is you&#39;re trying to match, the data that you&#39;re searching through, and the requirements and uses of the matched results. It won&#39;t take long until you gain an appreciation for Jamie Zawinski&#39;s infamous quote.</p>

  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://oreilly.com/catalog/9780596528126/" class="section-link printURL">O&#39;Reilly - Mastering Regular Expressions, 3rd edition by Jeffrey Friedl</a></li>
      <li><a href="http://regexlib.com/" class="section-link printURL">RegExLib.com - Regular Expression Library</a></li>
      <li><a href="http://userguide.icu-project.org/strings/regexp" class="section-link printURL">ICU Userguide - Regular Expressions</a></li>
      <li><a href="http://www.regular-expressions.info/" class="section-link printURL">Regular-Expressions.info - Regex Tutorial, Examples, and Reference</a></li>
      <li><a href="http://en.wikipedia.org/wiki/Regular_expression" class="section-link printURL">Wikipedia - Regular Expression</a></li>
    </ul>
  </div>

  <div class="enhancedCopyOnly screenOnly">

    <h3>Enhanced Copy To Clipboard Functionality</h3>
    
    <div class="box titled copyToClipboard preferences UIpane screenOnly" id="copyRegexToClipboardPreferences">
      <div class="title blueGrey">Copy Regex to Clipboard Preferences</div>
      <div class="contents alum2">
	
	<div class="UItopTitleSpacer">
	  
	  <div class="insetOuter"><div class="insetMiddle"><div class="inset">
		
		<table class="prefsUI" style="width: 100%;">
		  <tr id="copyRegexPrefsStyleRow" class="copyRegexPrefsRow">
		    <td class="UIlabel">Copied Regex Escape Style:</td>
		    <td colspan="2" class="UIcontrol" style="width: 58%;">
		      <select id="copyRegexPrefsStyle" class="copyRegexPrefsControl">
			<option>None</option>
			<option>Escape Only</option>
			<option>C String</option>
			<option>NSString</option>
		      </select>
		    </td>
		  </tr>
		  <tr id="copyRegexPrefsSmartEscapeRow" class="copyRegexPrefsRow">
		    <td class="UIlabel">Escape Style Options:</td>
		    <td class="UIcontrol"><input type=checkbox id="copyRegexPrefsSmartEscape" class="copyRegexPrefsControl"></td>
		    <td class="UIcontrolLabel"><span>Smart escape</span></td>
		  </tr>
		  <tr id="copyRegexPrefsUseC99Row" class="copyRegexPrefsRow">
		    <td class="UIlabel">&nbsp;</td>
		    <td class="UIcontrol"><input type=checkbox id="copyRegexPrefsUseC99" class="copyRegexPrefsControl"></td>
		    <td class="UIcontrolLabel"><span>Use <b>C99</b> <span class="code">\u</span> character escapes</span></td>
		  </tr>
		  <tr id="copyRegexPrefsUnicodeInNSStringsRow" class="copyRegexPrefsRow">
		    <td class="UIlabel">&nbsp;</td>
		    <td class="UIcontrol"><input type=checkbox id="copyRegexPrefsUnicodeInNSStrings" class="copyRegexPrefsControl"></td>
		    <td class="UIcontrolLabel"><span>Escaped Unicode in <span class="code">NSString</span> literals</span></td>
		  </tr>
		</table>

		
		<div class="prefWarnings" id="prefWarnings">
		  <hr class="beveled">
		  <div class="prefWarningsSpacer" id="prefWarningsSpacer">
		    <div class="table prefWarningsTable copyRegexPrefsWarning" id="smartEscapeWarning">
		      <div class="row prefWarning">
			<div class="cell label"><b>Note:</b></div>
			<div class="cell message">The escaped regular expression may be slightly different than the original because some escape sequences are parsed and rewritten.</div>
		      </div>
		    </div>
		    <div class="table prefWarningsTable copyRegexPrefsWarning" id="c99Warning">
		      <div class="row prefWarning">
			<div class="cell label"><b>Note:</b></div>
			<div class="cell message">Use of <span class="quotedText">\u</span> character escapes requires the <b>C99</b> standard with the execution character set set to <span class="quotedText">UTF-8</span> (the default for <span class="quotedText">gcc</span>).</div>
		      </div>
		    </div>
		    <div class="table prefWarningsTable copyRegexPrefsWarning" id="nsstringUnicodeWarning">
		      <div class="row prefWarning">
			<div class="cell label"><b>Note:</b></div>
			<div class="cell message">Escaped Unicode in <span class="code">NSString</span> literals requires <span class="hardNobr">Xcode &ge; 3.0</span> and <span class="hardNobr"><span class="quotedText">gcc</span> &ge; 4.0.</span></div>
		      </div>
		    </div>
		  </div>
		</div>
	  </div></div></div>
	  
	  <div class="clipboardExamples" id="topContainer">
	    <p class="UIlabel">Escape Style Preview:</p>
	    <div id="shadow">
	      <div id="clip">
		<script type="text/javascript">
		  var exampleRegexArray = ["(\\d+)", "[\\$|\u20AC]", "\"Yes\\?\\n\"", "\"([^\\\"]*)\"", "(?:SS|\u00df)"]; //"
		  document.writeln(buildPreviewTables("cbe_bg", "style='margin: 0px;'", exampleRegexArray));
		  document.writeln(buildPreviewTables("cbe_a", "style='margin: 0px; display: block;'", exampleRegexArray).replace(/class="([^"]*)"/, "class=\"$1 active\""));
		  document.writeln(buildPreviewTables("cbe_b", "style='margin: 0px; display: block;'", exampleRegexArray).replace(/class="([^"]*)"/, "class=\"$1 inactive\""));
		</script>
	      </div>
	    </div>
	  </div>
	</div>
      </div>
    </div>

    <div class="box titled screenOnly regexEscapeTool UIpane clearBoth noSelect" id="RegexEscapeTool">
      <div class="title blueGrey">Regex Escape Tool</div>
      <div class="contents alum2">
	<div class="UIcontentSpacer">
	  <div class="contain">
	    <textarea cols="30" rows="3" class="UIcontrol regex canSelect" id="interactiveEscapedInput">Number: \d+</textarea>
	  </div>
	  
	  <div style="margin-top: 0.25em;">
	    <p class="UIlabel noSelect" style="margin-bottom: 0.25em; margin-left: 0.5ex;">Preview:</p>
	    <div class="insetOuter"><div class="insetMiddle"><div class="inset">
		  <div class="UImessage regex doNotEscape canSelect" id="interactiveEscapedOutput">&nbsp;</div>
	    </div></div></div>
	  </div>
	</div>
      </div>
    </div>


    <p>This browser supports Copy To Clipboard features that can be used by this document.  Using the <a href="#copyRegexToClipboardPreferences">Copy Regex to Clipboard Preferences</a> interface, you can configure the behavior of <span class="context-menu">Edit </span><span class="submenuArrow">&#9658;</span><span class="context-menu"> Copy</span> so that when you select and copy a regular expression in this document, the clipboard will contain the selected regular expression that has been escaped according to your preference choices.  The resulting text in the clipboard can be pasted directly in to your source code, no further modification of the regular expression is required.</p>

    <p>Your preference choices are stored in the browser using a cookie.  Provided that cookies are enabled in your browser, your preferences should persist across browser sessions.  The preference panel also contains a preview of what would be copied to the clipboard for some example regular expressions using the current settings.  When you change a setting in the preferences, the examples will transition between the previous settings and the new settings, while briefly highlighting the differences between the two settings, so you can determine the effect the change has caused.</p>
    
    <p>Some of the problems of using regular expressions unmodified in <b>C</b> and <b class="hardNobr">Objective-C</b> are:</p>
    
    <ul class="square">
      <li>String literals in <b>C</b> use the <span class="consoleText" title="Backslash">\</span> character as the escape character.  Regular expressions typically make heavy use of the <span class="consoleText" title="Backslash">\</span> character and each use of the character must be escaped, resulting in <span class="consoleText" title="Backslash Backslash">\\</span>.</li>
      <li>The use of the <span class="consoleText" title="Quote">&quot;</span> quote character must be escaped, resulting in <span class="consoleText" title="Backslash Quote">\&quot;</span></li>
      <li>Unicode characters must be escaped in a compatible way.</li>
    </ul>
    
    <p>There are several different ways to escape Unicode characters.  When using Unicode characters in <span class="code">NSString</span> literals, the best method depends on the version of Xcode that is used to compile the source and what <b>C</b> standard you are using <span class="hardNobr">(i.e., <span class="consoleText">gcc -std=</span><span class="parameterChoice">(c|gnu)</span><span class="consoleText">99</span>)</span>.</p>
    
    <p>When the <span class="context-menu">Copied Regex Escape Style</span> is set to <span class="dialog-option">None</span>, then the selected regular expression is copied unmodified to the clipboard.</p>
    
    <p>When the <span class="context-menu">Copied Regex Escape Style</span> is set to <span class="dialog-option">Escape Only</span>, <span class="dialog-option">C String</span>, or <span class="dialog-option">NSString</span> then these details are automatically dealt with for you. This allows you to paste the selected regular expression directly in to your source code without having to escape every use of <span class="consoleText" title="Backslash">\</span> by hand, or having to convert the Unicode characters in to a acceptable format.</p>
    
    <h4>Escape Option Details</h4>

    <h5>Smart escape</h5>

    <p>If this option is <i><b>disabled</b></i> then all occurrences of <span class="consoleText" title="Backslash">\</span> and <span class="consoleText" title="Quote">&quot;</span> are escaped with a <span class="consoleText" title="Backslash">\</span>, resulting in <span class="consoleText" title="Backslash Backslash">\\</span> or <span class="consoleText" title="Backslash Quote">\&quot;</span>.  No other processing is performed.  Since this prevents the <b>C</b> compiler from interpreting any special meaning of <span class="consoleText" title="Backslash">\</span> sequences, it is the safest option.  The ICU regular expression engine is then responsible for interpreting the meaning of any <span class="hardNobr"><span class="consoleText" title="Backslash">\</span> escaped</span> character sequences.</p>
    
    <p>If this option is <i><b>enabled</b></i> then certain escape sequences are interpreted and rewritten using the current preference options.</p>

    <h5>Use <b>C99</b> <span class="consoleText">\u</span> character escapes</h5>

    <p>Normally, Unicode characters are embedded in string literals as the characters <span class="code hardNobr">UTF-8</span> byte sequence using <span class="hardNobr"><span class="consoleText">\</span><i>ddd</i></span> octal escapes.  When this option is enabled, the <b>C99</b> <span class="consoleText">\u</span> and <span class="consoleText">\U</span> character escape sequences are used instead.  <span class="consoleText">gcc</span> will issue a warning if <span class="consoleText">\u</span> character escape sequences are present and the compiler is not configured to use the <b>C99</b> (or later) standard <span class="hardNobr">(i.e., <span class="consoleText">gcc -std=</span><span class="parameterChoice">(c|gnu)</span><span class="consoleText">99</span>).</span></p>

    <p>Under the <b>C99</b> standard, <span class="consoleText">\u</span> and <span class="consoleText">\U</span> are used to specify a <i>universal character name</i>, which is a character encoded in the <span class="hardNobr">ISO/IEC 10646</span> character set (essentially identical to Unicode in this context).  Ultimately, a <i>universal character name</i> is translated in to a sequence of bytes needed to represent the designated character in the <b>C</b> environments <i>execution character set</i>.  Usually, although certainly not always, a string literal should be encoded as <span class="code hardNobr">UTF-8</span>, which happens to be the default <i>execution character set</i> for <span class="consoleText">gcc</span>.  This is an important point to remember because the more convenient and easier to use <span class="consoleText">\u</span> escape sequences are not guaranteed to convert in to a specific sequence of bytes, unlike an <span class="hardNobr">octal <span class="consoleText">\</span><i>ddd</i></span> or <span class="hardNobr">hex <span class="consoleText">\x</span><i>hh</i></span> escape sequence. There is currently no way to specify that a particular string literal should always be translated using a specific character set encoding. This may result in undefined behavior if the <span class="consoleText">\u</span> universal character name is not translated in to the expected character set, which in this case must be <span class="code hardNobr">UTF-8</span>.</p>

    <h5>Escaped Unicode in <span class="code">NSString</span> literals</h5>

    <p>Prior to Xcode 3.0, <span class="consoleText">gcc</span> only supported the use of <span class="code">ASCII</span> characters <span class="hardNobr">(i.e., characters &le; 127)</span> in constant <span class="code">NSString</span> literals.  If one needed to include Unicode characters in an <span class="code">NSString</span>, one would typically convert the string in to <span class="code hardNobr">UTF-8</span>, and then create a <span class="code">NSString</span> at run time using the <span class="code">stringWithUTF8String:</span> method, with the <span class="code hardNobr">UTF-8</span> encoded <b>C</b> string passed as the argument. For example, <span class="hardNobr">&quot;<span class="code">&euro;1.99</span>&quot;</span>, which contains the &euro; euro symbol, would be created using the following:</p>

<div class="box sourcecode">NSString *euroString = [NSString stringWithUTF8String:"\342\202\2541.99"]; // <span class="comment">or with C99 \u character escapes:</span>
NSString *euroString = [NSString stringWithUTF8String:"\u20ac1.99"];</div>

    <p>One of the obvious disadvantages of this approach is that it instantiates a new, autoreleased <span class="code">NSString</span> each time it&#39;s used, unlike a constant <span class="code">NSString</span> literal like <span class="code">@&quot;$1.99&quot;</span>. Beginning with Xcode 3.0 and gcc 4.0, constant <span class="code">NSString</span> literals that contain Unicode characters can be specified directly in source-code using the standard <span class="code">@&quot;&quot;</span> syntax.  For example:</p>

<div class="box sourcecode">NSString *euroString = @"\342\202\2541.99"; // <span class="comment">or with C99 \u character escapes:</span>
NSString *euroString = @"\u20ac1.99";</div>

    <p>The compiler converts these strings to <span class="code hardNobr">UTF-16</span> using the endianness of the target architecture.  Since <span class="hardNobr">Mach-O</span> object file format allows for multiple architectures, this allows each architecture to encode the string as native <span class="code hardNobr">UTF-16</span> byte ordering for that architecture, so there are no issues with proper byte ordering.  Within the object file itself, these strings are essentially identical to their <span class="hardNobr"><span class="code">ASCII</span>-only</span> counterparts: effectively they are pre-instantiated objects.  The only real difference is that the compiler sets some internal <span class="code">CFString</span> bits differently so that the <span class="code">CFString</span> object knows that the strings data is encoded as <span class="code hardNobr">UTF-16</span> and not simple <span class="hardNobr">8-bit</span> data.</p>

    <p>Although this functionality has been present since the release of 10.5, it has only recently been documented in <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/ObjectiveC/Articles/ocLanguageSummary.html#//apple_ref/doc/uid/TP30001163-CH3-TPXREF104" class="printURL section-link">The Objective-C 2.0 Programming Language - Compiler Directives</a>, under the <span class="hardNobr code">@&quot;string&quot;</span> entry.  A copy of the relevant text is provided below:</p>

    <div class="box quote"><p>On <span class="hardNobr">Mac OS X v10.4</span> and earlier, the string must be <span class="hardNobr code">7-bit</span> <span class="hardNobr"><span class="hardNobr code">ASCII</span>-encoded.</span> On <span class="hardNobr">Mac OS X v10.5</span> and later (with <span class="hardNobr">Xcode 3.0</span> and later), you can also use <span class="hardNobr code">UTF-16</span> encoded strings. (The runtime from <span class="hardNobr">Mac OS X v10.2</span> and later supports <span class="hardNobr code">UTF-16</span> encoded strings, so if you use <span class="hardNobr">Mac OS X v10.5</span> to compile an application for <span class="hardNobr">Mac OS X v10.2</span> and later, you can use <span class="hardNobr code">UTF-16</span> encoded strings.)</p></div>

    <h4>Visual Indication that the Selected Text has been Escaped</h4>
    
    <p>This document will briefly add a red outline around the selected text as a visual aid in determining whether or not the selected text was modified before placing it in the clipboard.  In addition to this, a <span title="Heads Up Display">HUD</span> display will drop down briefly at the top of the documents window and will display the escaped text that was placed in to the clipboard.  Here is an example of what would be displayed if the <span class="context-menu">NSString</span> escape style was selected:</p>


    <div class="table copyToClipboardDisplayExample"><div class="row">
	<div class="cell">The outline that is display when a regular expression is selected and copied to the clipboard: <span class="pulseOutlineRed" style="background: highlight; background: -moz-mac-accentregularhighlight; margin-left: 1ex; margin-right: 1.5ex; "><span class="regex">(\d+):\s*(.*)</span></span></div>
	<div class="cell">The drop down HUD that would be displayed:</div>
	<div class="cell">
	  <div class="screenOnly copyToClipboardHUD example">
	    <div class="top">
	      <div class="padding">
		<div class="copiedAs">Copied to Clipboard as:</div>
		<div class="regex copyToClipboardHUDRegex">@&quot;(\\d+):\\s*(.*)&quot;</div>
	      </div>
	    </div>
	  </div>
	</div>
    </div></div>

    <p>The selected text will only be escaped if it can be determined that it is a regular expression, and the selection only contains a regular expression. If the regular expression is part of an overall larger selection then the text that is copied to the clipboard is not modified.</p>

<div class="box note clearBoth"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>The method used to escape regular expressions is only a simple set of heuristics.  While these heuristics seem to work correctly for a variety of inputs, it is by no means error-free.  You should always double check the escaped output for errors.</p>
</div></div></div></div>

    <h4>Regex Escape Tool</h4>

    <p>Also available is the <a href="#RegexEscapeTool">Regex Escape Tool</a> which allows you to enter a regular expression and have it immediately escaped using the current preference settings.  This can be useful if you have a complex regular expression that needs to be escaped before you can use it in a constant <span class="code">NSString</span> literal.  It can also be used to easily create a constant <span class="code">NSString</span> literal that contains several Unicode characters that would otherwise have to be manually converted by hand.</p>

  </div> <!-- enhancedCopyOnly screenOnly -->
  
  <h3 style="clear: Both" id="RegexKitLiteCookbook_PatternMatchingRecipes">Pattern Matching Recipes</h3>

  <h4 id="RegexKitLiteCookbook_PatternMatchingRecipes_Numbers">Numbers</h4>
  
  <table class="slate regexList">
    <tr><th>Description</th><th>Regex</th><th>Examples</th></tr>
    <tr><td class="description">Integer</td><td class="regex">[+\-]?[0-9]+</td><td class="example"><span class="regexMatch">123</span><span class="regexMatch">-42</span><span class="regexMatch">+23</span></td></tr>
    <tr><td class="description">Hex Number</td><td class="regex">0[xX][0-9a-fA-F]+</td><td class="example"><span class="regexMatch">0x0</span><span class="regexMatch">0xdeadbeef</span><span class="regexMatch">0xF3</span></td></tr>
    <tr><td class="description">Floating Point</td><td class="regex">[+\-]?(?:[0-9]*\.[0-9]+|[0-9]+\.)</td><td class="example"><span class="regexMatch">123.</span><span class="regexMatch">.123</span><span class="regexMatch">+.42</span></td></tr>
    <tr><td class="description">Floating Point with Exponent</td><td class="regex">[+\-]?(?:[0-9]*\.[0-9]+|[0-9]+\.)(?:[eE][+\-]?[0-9]+)?</td><td class="example"><span class="regexMatch">123.</span><span class="regexMatch">.123</span><span class="regexMatch">10.0E13</span><span class="regexMatch">1.23e-7</span></td></tr>
    <tr><td class="description">Comma Separated Number</td><td class="regex">[0-9]{1,3}(?:,[0-9]{3})*</td><td class="example"><span class="regexMatch">42</span><span class="regexMatch">1,234</span><span class="regexMatch">1,234,567</span></td></tr>
    <tr><td class="description">Comma Separated Number</td><td class="regex">[0-9]{1,3}(?:,[0-9]{3})*(?:\.[0-9]+)?</td><td class="example"><span class="regexMatch">42</span><span class="regexMatch">1,234</span><span class="regexMatch">1,234,567.89</span></td></tr>
  </table>
  
  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_Numbers_ExtractingandConvertingNumbers">Extracting and Converting Numbers</h5>
  
  <p><span class="code">NSString</span> includes several methods for converting the contents of the string in to a numeric value in the various <b>C</b> primitive types.  The following demonstrates the matching of an <span class="code">int</span> and <span class="code">double</span> in a <span class="code">NSString</span>, and then converting the matched string in to its base type.</p>
  
  <div class="box sourcecode clearBoth"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Integer conversion&hellip;</span></span></div>NSString *searchString = @&quot;The int 5542 to convert&quot;;
NSString *regexString  = @&quot;([+\\-]?[0-9]+)&quot;;
int       matchedInt   = [[searchString <span class="hardNobr">stringByMatching:regexString</span> <span class="hardNobr">capture:1L]</span> <span class="hardNobr">intValue];</span></div>

  <p>The variable <span class="code">matchedInt</span> now contains the value of <span class="code">5542</span>.</p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Floating Point conversion&hellip;</span></span></div>NSString *searchString  = @&quot;The double 4321.9876 to convert&quot;;
NSString *regexString   = <span class="hardNobr">@&quot;([+\\-]?(?:[0-9]*\\.[0-9]+|[0-9]+\\.))&quot;;</span>
double    matchedDouble = [[searchString <span class="hardNobr">stringByMatching:regexString</span> <span class="hardNobr">capture:1L]</span> <span class="hardNobr">doubleValue];</span></div>

  <p>The variable <span class="code">matchedDouble</span> now contains the value of <span class="code">4321.9876</span>. <span class="code">doubleValue</span> can even convert numbers that are in scientific notation, which represent numbers <span class="hardNobr">as <i>n</i> &times; 10<sup><i>exp</i></sup>:</span></p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Floating Point conversion&hellip;</span></span></div>NSString *searchString  = @&quot;The double 1.010489e5 to convert&quot;;
NSString *regexString   = <span class="hardNobr">@&quot;([+\\-]?(?:[0-9]*\\.[0-9]+|[0-9]+\\.)(?:[eE][+\\-]?[0-9]+)?)&quot;;</span>
double    matchedDouble = [[searchString <span class="hardNobr">stringByMatching:regexString capture:1L]</span> <span class="hardNobr">doubleValue];</span></div>

  <p>The variable <span class="code">matchedDouble</span> now contains the value of <span class="code">101048.9</span>.</p>

  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_Numbers_ExtractingandConvertingHexNumbers">Extracting and Converting Hex Numbers</h5>

  <p>Converting a string that contains a hex number in to a more basic type, such as an <span class="code">int</span>, takes a little more work.  Unfortunately, Foundation does not provide an easy way to convert a hex value in a string in to a more basic type as it does with <span class="code">intValue</span> or <span class="code">doubleValue</span>.  Thankfully the standard <b>C</b> library provides a set of functions for performing such a conversion.  For this example we will use the <span class="code">strtol()</span> (<i>string to long</i>) function to convert the hex value we&#39;ve extracted from <span class="code">searchString</span>.  We can not pass the pointer to the <span class="code">NSString</span> object that contains the matched hex value since <span class="code">strtol()</span> is part of the standard <b>C</b> library which can only work on pointers to <b>C</b> strings.  We use the <span class="code">UTF8String</span> method to get a pointer to a compatible <b>C</b> string of the matched hex value.</p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Hex conversion&hellip;</span></span></div>NSString *searchString = @&quot;A hex value: 0x0badf00d&quot;;
NSString *regexString  = @&quot;\\b(0[xX][0-9a-fA-F]+)\\b&quot;;

NSString *hexString    = [searchString stringByMatching:regexString <span class="hardNobr">capture:1L];</span>

// <span class="comment">Use strtol() to convert the string to a long.</span>
long hexLong = strtol([hexString UTF8String], NULL, 16);

NSLog(@&quot;hexLong: 0x%lx / %ld&quot;, (u_long)hexLong, hexLong);
// <span class="comment">2008-09-01 09:40:44.848 hex_example[30583:807] hexLong: 0xbadf00d / 195948557</span></div>

  <p>The full set of <i>string to&hellip;</i> functions are: <span class="code">strtol()</span>, <span class="code">strtoll()</span>, <span class="code">strtoul()</span>, and <span class="code">strtoull()</span>.  These convert a string value, from base 2 to base 36, in to a <span class="code">long</span>, <span class="code">long long</span>, <span class="code">unsigned long</span>, and <span class="code">unsigned long long</span> respectively.</p>

  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_Numbers_AddingHexValueConversionstoNSString">Adding Hex Value Conversions to <span class="code">NSString</span></h5>

  <p>Since it seems to be a frequently asked question, and a common search engine query for RegexKit web site visitors, here is a <span class="code">NSString</span> category addition that converts the receivers text in to a <span class="code">NSInteger</span> value.  This is the same functionality as <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/intValue" class="code">intValue</a> or <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/doubleValue" class="code">doubleValue</a>, except that it converts hexadecimal text values instead of decimal text values.</p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>The following code can also be found in the <span class="rkl">RegexKit<i>Lite</i></span> distributions <span class="file">examples/</span> directory.</p>
</div></div></div></div>

<p>The example conversion code is fairly quick since it uses <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> directly along with the stack to hold any temporary string conversions.  Any whitespace at the beginning of the string will be skipped and the hexadecimal text to be converted may be optionally prefixed with either <span class="consoleText">0x</span> or <span class="consoleText">0X</span>.  Returns <span class="code">0</span> if the receiver does not begin with a valid hexadecimal text representation. Refer to <a href="http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man3/strtol.3.html" class="code">strtol(3)</a> for additional conversion details.</p>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>If the receiver needs to be converted in to an encoding that is compatible with <span class="code">strtol()</span>, only the first sixty characters of the receiver are converted.</p>
</div></div></div></div>

<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">NSString-HexConversion.h</span></span></div>#import &lt;Foundation/NSString.h&gt;

@interface NSString (HexConversion)
-(NSInteger)hexValue;
@end</div>

<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">NSString-HexConversion.m</span></span></div>#import &quot;NSString-HexConversion.h&quot;
#import &lt;CoreFoundation/CFString.h&gt;
#include &lt;stdlib.h&gt;

@implementation NSString (HexConversion)

-(NSInteger)hexValue
{
  CFStringRef cfSelf = (CFStringRef)self;
  UInt8 buffer[64];
  const char *cptr;

  if((cptr = CFStringGetCStringPtr(cfSelf, kCFStringEncodingMacRoman)) == NULL) {
    CFRange range     = CFRangeMake(0L, CFStringGetLength(cfSelf));
    CFIndex usedBytes = 0L;
    CFStringGetBytes(cfSelf, range, kCFStringEncodingUTF8, &#39;?&#39;, false, buffer, 60L, &amp;usedBytes);
    buffer[usedBytes] = 0;
    cptr              = (const char *)buffer;
  }

  return((NSInteger)strtol(cptr, NULL, 16));
}

@end</div>

  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man3/strtol.3.html" class="code">strtol(3)</a></li>
      <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/intValue" class="code">- intValue</a></li>
      <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/instm/NSString/doubleValue" class="code">- doubleValue</a></li>
    </ul>
  </div>
  
  <h4 id="RegexKitLiteCookbook_PatternMatchingRecipes_TextFiles">Text Files</h4>
  
  <table class="slate regexList">
    <tr><th>Description</th><th>Regex</th></tr>
    <tr><td class="description">Empty Line</td><td class="regex">(?m:^$)</td></tr>
    <tr><td class="description">Empty or Whitespace Only Line</td><td class="regex">(?m-s:^\s*$)</td></tr>
    <tr><td class="description">Strip Leading Whitespace</td><td class="regex">(?m-s:^\s*(.*?)$)</td></tr>
    <tr><td class="description">Strip Trailing Whitespace</td><td class="regex">(?m-s:^(.*?)\s*$)</td></tr>
    <tr><td class="description">Strip Leading and Trailing Whitespace</td><td class="regex">(?m-s:^\s*(.*?)\s*$)</td></tr>
    <tr><td class="description">Quoted String, Can Span Multiple Lines, May Contain \&quot;</td><td class="regex">&quot;(?:[^&quot;\\]*+|\\.)*&quot;</td></tr>
    <tr><td class="description">Quoted String, Single Line Only, May Contain \&quot;</td><td class="regex">&quot;(?:[^&quot;\\\r\n]*+|\\[^\r\n])*&quot;</td></tr>
    <tr><td class="description">HTML Comment</td><td class="regex">(?s:&lt;&#45;&#45;.*?&#45;&#45;&gt;)</td></tr>
    <tr><td class="description">Perl / Shell Comment</td><td class="regex">(?m-s:#.*$)</td></tr>
    <tr><td class="description">C, C++, or ObjC Comment</td><td class="regex">(?m-s://.*$)</td></tr>
    <tr><td class="description">C, C++, or ObjC Comment and Leading Whitespace</td><td class="regex">(?m-s:\s*//.*$)</td></tr>
    <tr><td class="description">C, C++, or ObjC Comment</td><td class="regex">(?s:/\*.*?\*/)</td></tr>
  </table>

  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_TextFiles_TheNewlineDebacle">The Newline Debacle</h5>

  <p>Unfortunately, when processing text files, there is no standard &#39;newline&#39; character or character sequence.  Today this most commonly surfaces when converting text between Microsoft Windows / MS-DOS and Unix / <span class="hardNobr">Mac OS X</span>.  The reason for the proliferation of newline standards is largely historical and goes back many decades.  Below is a table of the dominant newline character sequence &#39;standards&#39;:</p>

  <table class="slate charactersList">
    <tr><th>Description</th><th>Sequence</th><th>C String</th><th>Control</th><th>Common Uses</th></tr>
    <tr><td>Line Feed</td><td class="characters">\u000A</td><td class="consoleText">\n</td><td class="consoleText">^J</td><td>Unix, Amiga, Mac OS X</td></tr>
    <tr><td>Vertical Tab</td><td class="characters">\u000B</td><td class="consoleText">\v</td><td class="consoleText">^K</td><td>&nbsp;</td></tr>
    <tr><td>Form Feed</td><td class="characters">\u000C</td><td class="consoleText">\f</td><td class="consoleText">^L</td><td>&nbsp;</td></tr>
    <tr><td>Carriage Return</td><td class="characters">\u000D</td><td class="consoleText">\r</td><td class="consoleText">^M</td><td>Apple ][, Mac OS &le; 9</td></tr>
    <tr><td>Next Line (NEL)</td><td class="characters">\u0085</td><td class="consoleText">&nbsp;</td><td class="consoleText"></td><td>IBM / EBCDIC</td></tr>
    <tr><td>Line Separator</td><td class="characters">\u2028</td><td class="consoleText">&nbsp;</td><td class="consoleText"></td><td>Unicode</td></tr>
    <tr><td>Paragraph Separator</td><td class="characters">\u2029</td><td class="consoleText">&nbsp;</td><td class="consoleText"></td><td>Unicode</td></tr>
    <tr><td>Carriage Return + Line Feed</td><td class="characters">\u000D\u000A</td><td class="consoleText">\r\n</td><td class="consoleText">^M^J</td><td>MS-DOS, Windows</td></tr>
  </table>
  
  <p>Ideally, one should be flexible enough to accept any of these character sequences if one has to process text files, especially if the origin of those text files is not known.  Thankfully, regular expressions excel at just such a task.  Below is a regular expression pattern that will match any of the above character sequences.  This is also the character sequence that the metacharacter <span class="regex">$</span> matches.</p>

  <table class="slate regexList">
    <tr><th>Description</th><th>Regex</th><th>Notes</th></tr>
    <tr><td class="description">Any newline</td><td class="regex">(?:\r\n|[\n\v\f\r\x85\p{Zl}\p{Zp}])</td><td class="note">UTS #18 recommended. Character sequence that <span class="regex">$</span> matches.</td></tr>
  </table>

  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://www.unicode.org/reports/tr18/#Line_Boundaries" class="section-link printURL">UTS #18: Unicode Regular Expressions - Line Boundaries</a></li>
      <li><a href="http://en.wikipedia.org/wiki/Newline" class="section-link printURL">Wikipedia - Newline</a></li>
    </ul>
  </div>

  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_TextFiles_MatchingtheBeginningandEndofaLine">Matching the Beginning and End of a Line</h5>

<p>It is often necessary to work with the individual lines of a file. There are two regular expression metacharacters, <span class="regex">^</span> and <span class="regex">$</span>, that match the <i>beginning</i> and <i>end</i> of a line, respectively. However, exactly what is matched by <span class="regex">^</span> and <span class="regex">$</span> depends on whether or not the <span class="regex-def">multi-line</span> option is enabled for the regular expression, which by default is disabled. It can be enabled for the entire regular expression by passing <a href="#RKLRegexOptions_RKLMultiline" class="code">RKLMultiline</a> via the <span class="code">options:</span> method argument, or within the regular expression using the options syntax&mdash; <span class="regex">(?m:</span>&hellip;<span class="regex">)</span>.</p>

<p>If <span class="regex-def">multi-line</span> is <b><i>disabled</i></b>, then <span class="regex">^</span> and <span class="regex">$</span> match the beginning and end of the entire string.  If there is a <span class="regex-def">newline</span> character sequence at the very end of the string, then <span class="regex">$</span> will match the character just before the <span class="regex-def">newline</span> character sequence.  Any <span class="regex-def">newline</span> character sequences in the middle of the string will <b><i>not</i></b> be matched.</p>

<p>If <span class="regex-def">multi-line</span> is <b><i>enabled</i></b>, then <span class="regex">^</span> and <span class="regex">$</span> match the beginning and end of a line, where the end of a line is the <span class="regex-def">newline</span> character sequence.  The metacharacter <span class="regex">^</span> matches either the first character in the string, or the first character following a <span class="regex-def">newline</span> character sequence.  The metacharacter <span class="regex">$</span> matches either the last character in the string, or the character just before a <span class="regex-def">newline</span> character sequence.</p>


  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_TextFiles_CreatingaNSArrayContainingEveryLineinaString">Creating a <span class="code">NSArray</span> Containing Every Line in a String</h5>

  <p>A common text processing pattern is to process a file one line at a time.  Using the recommended regular expression for matching any newline and the <a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">componentsSeparatedByRegex:</a> method, you can easily create a <span class="code">NSArray</span> containing every line in a file and process it one line at a time:</p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Process every line&hellip;</span></span></div>NSString *fileNameString = @&quot;example&quot;;
NSString *regexString    = <span class="hardNobr">@&quot;(?:\r\n|[\n\v\f\r\302\205\\p{Zl}\\p{Zp}])&quot;;</span>
NSError  *error          = NULL;
NSString *fileString     = [NSString <span class="hardNobr">stringWithContentsOfFile:fileNameString</span> <span class="hardNobr">usedEncoding:NULL</span> <span class="hardNobr">error:&amp;error];</span>

if(fileString) {
  NSArray *linesArray = [fileString <span class="hardNobr">componentsSeparatedByRegex:regexString];</span>

  for(NSString *lineString in linesArray) { <span class="hardNobr">// <span class="comment">ObjC 2.0 for&hellip;in loop.</span></span>
    // <span class="comment">Per line processing.</span>

  }
} else {
  NSLog(@&quot;Error reading file &#39;%@&#39;&quot;, fileNameString);
  if(error) { NSLog(@&quot;Error: %@&quot;, error); }
}</div>

  <p>The <a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">componentsSeparatedByRegex:</a> method effectively &#39;chops off&#39; the matched regular expression, or in this case any newline character.  In the example above, within the <span class="code">for&hellip;in</span> loop, <span class="code">lineString</span> will not have a newline character at the end of the string.</p>

  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_TextFiles_ParsingCSVData">Parsing CSV Data</h5>

  <table class="slate regexList">
    <tr><th>Description</th><th>Regex</th></tr>
    <tr><td class="description">Split CSV line</td><td class="regex">
<span class="softNobr">
<span class="tbrOn">,(?=(?:(?:[^&quot;\\]*+|\\&quot;)*&quot;(?:[^&quot;\\]*+|\\&quot;)*&quot;)&#8203;*(?!(?:[^&quot;\\]*+|\\&quot;)*&quot;(?:[^&quot;\\]*+|\\&quot;)*$))</span>
<span class="tbrOff">,(?=(?:(?:[^&quot;\\]*+|\\&quot;)*&quot;(?:[^&quot;\\]*+|\\&quot;)*&quot;)*(?!(?:[^&quot;\\]*+|\\&quot;)*&quot;(?:[^&quot;\\]*+|\\&quot;)*$))</span>
</span>
</td></tr>
  </table>

  <p>This regular expression essentially works by ensuring that there are an even number of unescaped <span class="regex">&quot;</span> quotes following a <span class="regex">,</span> comma.  This is done by using <i>look-head assertions</i>.  The first <i>look-head assertion</i>, <span class="regex">(?=</span>, is a pattern that matches zero or more strings that contain two <span class="regex">&quot;</span> characters.  Then, a <i>negative look-head assertion</i> matches a single, unpaired <span class="regex">&quot;</span> quote character remaining at the <span class="regex">$</span> end of the line. It also uses <i>possessive matches</i> in the form of <span class="regex">*+</span> for speed, which prevents the regular expression engine from backtracking excessively. It&#39;s certainly not a beginners regular expression.</p>

  <p>The following is used as a substitute for a CSV data file in the example below.</p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Example CSV data&hellip;</span></span></div><span class="printOnly"><br></span>NSString *csvFileString <span class="softNobr">= @&quot;RegexKitLite,1.0,\&quot;Mar 23, 2008\&quot;,27004\n&quot;</span>
                          <span class="softNobr">@&quot;RegexKitLite,1.1,\&quot;Mar 28, 2008\&quot;,28081\n&quot;</span>
                          <span class="softNobr">@&quot;RegexKitLite,1.2,\&quot;Apr 01, 2008\&quot;,28765\n&quot;</span>
                          <span class="softNobr">@&quot;RegexKitLite,2.0,\&quot;Jul 07, 2008\&quot;,40569\n&quot;</span>
                          <span class="softNobr">@&quot;RegexKitLite,2.1,\&quot;Jul 12, 2008\&quot;,40660\n&quot;;</span></div>


  <p>This example really highlights the power of regular expressions when it comes to processing text. It takes just 17 lines, which includes comments, to parse a CSV data file of any newline type and create a <i>row</i> by <i>column</i> of <span class="code">NSArray</span> values of the results while correctly handling <span class="regex">&quot;</span> quoted values, including escaped <span class="regex">\&quot;</span> quotes.</p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Parse CSV data&hellip;</span></span></div><span class="printOnly"><br></span>NSString   *newlineRegex      <span class="hardNobr">= @&quot;(?:\r\n|[\n\v\f\r\\x85\\p{Zl}\\p{Zp}])&quot;;</span>
NSString   *splitCSVLineRegex <span class="softNobr">= @&quot;<span class="softNobr"><span class="tbrOn">,(?=(?:(?:[^\&quot;\\\\]*+|\\\\\&quot;)*&#8203;\&quot;(?:[^\&quot;\\\\]*+|\\\\\&quot;)*\&quot;)*&#8203;(?!(?:[^\&quot;\\\\]*+|\\\\\&quot;)*&#8203;\&quot;(?:[^\&quot;\\\\]*+|\\\\\&quot;)*$))</span><span class="tbrOff">,(?=(?:(?:[^\&quot;\\\\]*+|\\\\\&quot;)*\&quot;(?:[^\&quot;\\\\]*+|\\\\\&quot;)*\&quot;)*(?!(?:[^\&quot;\\\\]*+|\\\\\&quot;)*\&quot;(?:[^\&quot;\\\\]*+|\\\\\&quot;)*$))</span></span>&quot;;</span>

// <span class="comment">Create a NSArray of every line in csvFileString.</span>
NSArray    *csvLinesArray     = <span class="hardNobr">[csvFileString componentsSeparatedByRegex:</span><span class="hardNobr">newlineRegex];</span>

// <span class="comment">Create an id array to hold the comma split line results.</span>
id          splitLines[[csvLinesArray count]]; // <span class="comment">C99 variable length array.</span>
NSUInteger  splitLinesIndex = 0UL; <span class="screenOnly">&nbsp;           </span>// <span class="comment">Index of next splitLines[] member.</span>

for(NSString *csvLineString in csvLinesArray) { <span class="screenOnly">&nbsp;              </span>// <span class="comment">ObjC 2 for&hellip;in loop.</span>
  if([csvLineString <span class="hardNobr">isMatchedByRegex:@&quot;^\\s*$&quot;])</span> <span class="hardNobr">{ continue; }</span> // <span class="comment">Skip empty lines.</span>
  splitLines[splitLinesIndex++] = [csvLineString <span class="hardNobr">componentsSeparatedByRegex:</span><span class="hardNobr">splitCSVLineRegex];</span>
}

// <span class="comment">Gather up all the individual comma split results in to a single NSArray.</span>
NSArray *splitLinesArray = [NSArray <span class="hardNobr">arrayWithObjects:</span><span class="hardNobr">&amp;splitLines[0]</span> <span class="hardNobr">count:</span><span class="hardNobr">splitLinesIndex];</span></div>

  <h4 id="RegexKitLiteCookbook_PatternMatchingRecipes_NetworkandURL">Network and URL</h4>

  <table class="slate regexList">
    <tr><th>Description</th><th>Regex</th></tr>
    <tr><td class="description">HTTP</td><td class="regex">\bhttps?://[a-zA-Z0-9\-.]+(?:(?:/[a-zA-Z0-9\-._?,&#39;+\&amp;%$=~*!():@\\]*)+)?</td></tr>
    <tr><td class="description">HTTP</td><td class="regex">\b(https?)://([a-zA-Z0-9\-.]+)((?:/[a-zA-Z0-9\-._?,&#39;+\&amp;%$=~*!():@\\]*)+)?</td></tr>
    <tr><td class="description">HTTP</td><td class="regex">\b(https?)://(?:(\S+?)(?::(\S+?))?@)?([a-zA-Z0-9\-.]+)(?::(\d+))?((?:/[a-zA-Z0-9\-._?,&#39;+\&amp;%$=~*!():@\\]*)+)?</td></tr>
    <tr><td class="description">E-Mail</td><td class="regex">\b([a-zA-Z0-9%_.+\-]+)@([a-zA-Z0-9.\-]+?\.[a-zA-Z]{2,6})\b</td></tr>
    <tr><td class="description">Hostname</td><td class="regex">\b(?:[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}?[a-zA-Z0-9]\.)+[a-zA-Z]{2,6}\b</td></tr>
    <tr><td class="description">IP</td><td class="regex">\b(?:\d{1,3}\.){3}\d{1,3}\b</td></tr>
    <tr><td class="description">IP with Optional Netmask</td><td class="regex">\b((?:\d{1,3}\.){3}\d{1,3})(?:/(\d{1,2}))?\b</td></tr>
    <tr><td class="description">IP or Hostname</td><td class="regex">\b(?:(?:\d{1,3}\.){3}\d{1,3}|(?:[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}?[a-zA-Z0-9]\.)+[a-zA-Z]{2,6})\b</td></tr>
  </table>

  <h5 id="RegexKitLiteCookbook_PatternMatchingRecipes_NetworkandURL_CreatingaNSDictionaryofURLInformation">Creating a <span class="code">NSDictionary</span> of URL Information</h5>

  <p>The following example demonstrates how to match several fields in a URL and create a <span class="code">NSDictionary</span> with the extracted results.  Only the capture groups that result in a successful match will create a corresponding key in the dictionary.</p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">HTTP URL&hellip;</span></span></div>NSString *searchString = <span class="softNobr">@&quot;http://johndoe:secret@www.example.com:8080/private/mail/index.html&quot;;</span>
NSString *regexString  = <span class="softNobr">@&quot;\\b(https?)://(?:(\\S+?)(?::(\\S+?))?@)?([a-zA-Z0-9\\-.]+)(?::(\\d+))?((?:/[a-zA-Z0-9\\-._?,&#39;+\\&amp;%$=~*!():@\\\\]*)+)?&quot;;</span>

if([searchString isMatchedByRegex:regexString]) {
  NSString *protocolString = [searchString <span class="softNobr">stringByMatching:regexString</span> <span class="softNobr">capture:1L];</span>
  NSString *userString     = [searchString <span class="softNobr">stringByMatching:regexString</span> <span class="softNobr">capture:2L];</span>
  NSString *passwordString = [searchString <span class="softNobr">stringByMatching:regexString</span> <span class="softNobr">capture:3L];</span>
  NSString *hostString     = [searchString <span class="softNobr">stringByMatching:regexString</span> <span class="softNobr">capture:4L];</span>
  NSString *portString     = [searchString <span class="softNobr">stringByMatching:regexString</span> <span class="softNobr">capture:5L];</span>
  NSString *pathString     = [searchString <span class="softNobr">stringByMatching:regexString</span> <span class="softNobr">capture:6L];</span>

  NSMutableDictionary *urlDictionary = <span class="softNobr">[NSMutableDictionary dictionary];</span>

  if(protocolString) { [urlDictionary <span class="softNobr">setObject:protocolString</span> <span class="softNobr">forKey:@&quot;protocol&quot;];</span> }
  if(userString)     { [urlDictionary <span class="softNobr">setObject:userString</span>     <span class="softNobr">forKey:@&quot;user&quot;];</span>     }
  if(passwordString) { [urlDictionary <span class="softNobr">setObject:passwordString</span> <span class="softNobr">forKey:@&quot;password&quot;];</span> }
  if(hostString)     { [urlDictionary <span class="softNobr">setObject:hostString</span>     <span class="softNobr">forKey:@&quot;host&quot;];</span>     }
  if(portString)     { [urlDictionary <span class="softNobr">setObject:portString</span>     <span class="softNobr">forKey:@&quot;port&quot;];</span>     }
  if(pathString)     { [urlDictionary <span class="softNobr">setObject:pathString</span>     <span class="softNobr">forKey:@&quot;path&quot;];</span>     }

  NSLog(@&quot;urlDictionary: %@&quot;, urlDictionary);
}</div>

  <p><span class="rkl">RegexKit<i>Lite</i></span> 4.0 adds a new method, <span class="code">dictionaryByMatchingRegex:&hellip;</span>, that makes the creation of <span class="code">NSDictionary</span> objects like this much easier, as the following example demonstrates:</p>

  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta"><span class="rkl">RegexKit<i>Lite</i></span> &ge; 4.0 example&hellip;</span></span></div>NSString *searchString = <span class="softNobr">@&quot;http://johndoe:secret@www.example.com:8080/private/mail/index.html&quot;;</span>
NSString *regexString  = <span class="softNobr">@&quot;\\b(https?)://(?:(\\S+?)(?::(\\S+?))?@)?([a-zA-Z0-9\\-.]+)(?::(\\d+))?((?:/[a-zA-Z0-9\\-._?,&#39;+\\&amp;%$=~*!():@\\\\]*)+)?&quot;;</span>

NSDictionary *urlDictionary = [searchString <span class="softNobr">dictionaryByMatchingRegex:regexString</span>
                                                  <span class="softNobr">withKeysAndCaptures:@&quot;protocol&quot;, 1,</span> <span class="softNobr">@&quot;user&quot;, 2,</span> <span class="softNobr">@&quot;password&quot;, 3,</span> <span class="softNobr">@&quot;host&quot;, 4,</span> <span class="softNobr">@&quot;port&quot;, 5,</span> <span class="softNobr">@&quot;path&quot;, 6,</span> <span class="softNobr">NULL];</span>

if(urlDictionary != NULL) {<span class="softNobr"> NSLog(@&quot;urlDictionary: %@&quot;, urlDictionary);</span> }</div>

  <div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
    <p>Other than the difference in mutability for the dictionary containing the result, the <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 4.0</span> <span class="code">dictionaryByMatchingRegex:&hellip;</span> example produces the same result as the more verbose, <span class="hardNobr">pre-4.0</span> example.</p>
  </div></div></div></div>

  <p>These examples can form the basis of a function or method that takes a <span class="code">NSString</span> as an argument and returns a <span class="code">NSDictionary</span> as a result, maybe even as a category addition to <span class="code">NSString</span>.  The following is the output when the examples above are compiled and run:</p>

  <div class="box shell"><span class="shellOutput">shell% </span><span class="userInput">./http_example<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">2008-09-01 10:57:55.245 test_nsstring[31306:807] urlDictionary: {
    host = &quot;www.example.com&quot;;
    password = secret;
    path = &quot;/private/mail/index.html&quot;;
    port = 8080;
    protocol = http;
    user = johndoe;
}
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div>

</div>


<div class="printPageBreakAfter">
<h2 id="AddingRegexKitLitetoyourProject">Adding <span class="rkl">RegexKit<i>Lite</i></span> to your Project</h2>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>The following outlines a typical set of steps that one would perform. This is not the only way, nor the required way to add <span class="rkl">RegexKit<i>Lite</i></span> to your application.  They may not be correct for your project as each project is unique.  They are an overview for those unfamiliar with adding additional shared libraries to the list of libraries your application links against.</p>
</div></div></div></div>

<h3 id="AddingtheRegexKitframeworktoyourProject_OutlineofRequiredSteps">Outline of Required Steps</h3>

<p>The following outlines the steps required to use <span class="rkl">RegexKit<i>Lite</i></span> in your project.</p>

<ul class="square">
<li>Linking your application to the ICU dynamic shared library.</li>
<li>Adding the <span class="file">RegexKitLite.m</span> and <span class="file">RegexKitLite.h</span> files to your project and application target.</li>
<li>Import the <span class="file">RegexKitLite.h</span> header.</li>
</ul>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://developer.apple.com/mac/library/documentation/DeveloperTools/Conceptual/XcodeBuildSystem/500-Linking/bs_linking.html" class="section-link printURL">Xcode Build System Guide - Linking</a></li>
  </ul>
</div>

<h4 id="AddingRegexKitLitetoyourProject_AddingRegexKitLiteusingXcode">Adding <span class="rkl">RegexKit<i>Lite</i></span> using Xcode</h4>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">These instructions apply to <span class="hardNobr">Xcode versions 2.4.1 and 3.0.</span>  Other versions should be similar, but may vary for specific details.</div></div></div></div>

<p>Unfortunately, adding additional dynamic shared libraries that your application links to is not a straightforward process in Xcode, nor is there any recommended standard way.  Two options are presented below&mdash; the first is the &#39;easy&#39; way that alters your applications Xcode build settings to pass an additional command line argument directly to the linker.  The second option attempts to add the ICU dynamic shared library to the list of resources for your project and configuring your executable to link against the added resource.</p>

<p>The &#39;easy&#39; way is the recommended way to link against the ICU dynamic shared library.</p>

<h5>The Easy Way To Add The ICU Library</h5>

<ol>
  <li><p>First, determine the build settings layer of your project that should have altered linking configuration change applied to.  The build settings in Xcode are divided in to layers and each layer inherits the build settings from the layer above it. The top, global layer is <span class="context-menu">Project Settings</span>, followed by <span class="context-menu">Target Settings</span>, and finally the most specific layer <span class="context-menu">Executable Settings</span>.  If your project is large enough to have multiple targets and executables, you probably have an idea which layer is appropriate.  If you are unsure or unfamiliar with the different layers, <span class="context-menu">Target Settings</span> is recommended.</p></li>

<li><p>Select the appropriate layer from the <span class="context-menu">Project</span> menu.  If you are unsure, <span class="context-menu hardNobr">Project </span><span class="submenuArrow">&#9658;</span><span class="context-menu"> Edit Active Target</span> is recommended.</p></li>

<li><p>Select <span class="context-menu">Build</span> from the tab near the top of the <span class="context-menu">Target Info</span> window.  Find the <span class="code hardNobr">Other Linker Flags</span> build setting from the many build settings available and edit it. Add <span class="consoleText hardNobr">-licucore</span> <span class="hardNobr"><b>[</b><i>dash</i> <i>ell</i> <i>icucore</i></span> as a single word, without <span class="hardNobr">spaces<b>]</b>.</span>  If there are already other flags present, it is recommended that you add <span class="consoleText hardNobr">-licucore</span> to the end of the existing flags.</p>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">If other linker flags are present, there must be at least one space separating <span class="consoleText hardNobr">-licucore</span> from the other linker flags. For example, <span class="consoleText hardNobr">-flag1 -licucore -flag2</span></div></div></div></div>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">The <span class="context-menu">Configuration</span> drop down menu controls which build configuration the changes you make are applied to.  <span class="context-menu hardNobr">All Configurations</span> should be selected if this is the first time your are making these changes.</div></div></div></div>
</li>

<li>Follow the <span class="section-link">Add The <span class="rkl">RegexKit<i>Lite</i></span> Source Files To Your Project</span> steps below.</li>

</ol>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://developer.apple.com/mac/library/documentation/DeveloperTools/Conceptual/XcodeBuildSystem/300-Build_Settings/bs_build_settings.html" class="section-link">Xcode Build System Guide - Build Settings</a></li>
  </ul>
</div>

<h5>The Hard Way To Add The ICU Library</h5>

<ol>

<li><p>First, add the ICU dynamic shared library to your Xcode project.  You may choose to add the library to any group in your project, and which groups are created by default is dependent on the template type you chose when you created your project.  For a typical Cocoa application project, a good choice is the <span class="xcode-group">Frameworks</span> group.  To add the ICU dynamic shared library, control/right-click on the <span class="xcode-group">Framework</span> group and choose <span class="context-menu">Add </span><span class="submenuArrow">&#9658;</span><span class="context-menu"> Existing Files&hellip;</span></p></li>

<li><p>Next, you will need to choose the ICU dynamic shared library file to add.  Exactly which file to choose depends on your project, but a fairly safe choice is to select <span class="file">/Developer/SDKs/MacOSX10.6.sdk/usr/lib/libicucore.dylib</span>. You may have installed your developer tools in a different location than the default <span class="file">/Developer</span> directory, and the <span class="hardNobr">Mac OS X</span> SDK version should be the one your project is targeting, typically the latest one available.</p></li>

<li><p>Then, in the dialog that follows, make sure that <span class="dialog-option">Copy items into&hellip;</span> is unselected.  Select the targets you will be using <span class="rkl">RegexKit<i>Lite</i></span> in and then click <span class="context-menu">Add</span> to add the ICU dynamic shared library to your project.</p></li>

<li><p>Once the ICU dynamic shared library is added to your project, you will need to add it to the libraries that your executable is linked with.  To do so, expand the <span class="xcode-group">Targets</span> group, and then expand the executable targets you will be using <span class="rkl">RegexKit<i>Lite</i></span> in.  You will then need to select the <span class="file">libicucore.dylib</span> file that you added in the previous step and drag it in to the <span class="xcode-group">Link Binary With Libraries</span> group for each executable target that you will be using <span class="rkl">RegexKit<i>Lite</i></span> in.  The order of the files within the <span class="xcode-group">Link Binary With Libraries</span> group is not important, and for a typical Cocoa application the group will contain the <span class="file">Cocoa.framework</span> file.</p></li>

</ol>

<h5>Add The <span class="rkl">RegexKit<i>Lite</i></span> Source Files To Your Project</h5>

<ol>

 <li><p>Next, add the <span class="rkl">RegexKit<i>Lite</i></span> source files to your Xcode project.  In the <span class="xcode-group">Groups &amp; Files</span> outline view on the left, <span class="hardNobr">control/right-click</span> on the group that would like to add the files to, then select <span class="hardNobr"><span class="context-menu">Add </span><span class="submenuArrow">&#9658;</span><span class="context-menu"> Existing Files&hellip;</span></span></p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>You can perform the following steps once for each file (<span class="file">RegexKitLite.h</span> and <span class="file">RegexKitLite.m</span>), or once by selecting both files from the file dialog.</p>
</div></div></div></div>
</li>

<li><p>Select the <span class="file">RegexKitLite.h</span> and / or <span class="file">RegexKitLite.m</span> file from the file chooser dialog.</p></li>

<li><p>The next dialog will present you with several options.  If you have not already copied the <span class="rkl">RegexKit<i>Lite</i></span> files in to your projects directory, you may want to click on the <span class="dialog-option">Copy items into&hellip;</span> option.  Select the targets that you would like add the <span class="rkl">RegexKit<i>Lite</i></span> functionality to.</p></li>

<li><p>Finally, you will need to include the <span class="file">RegexKitLite.h</span> header file.  The best way to do this is very dependent on your project.  If your project consists of only half a dozen source files, you can add:</p>

<div class="box sourcecode">#import "RegexKitLite.h"</div>

<p>manually to each source file that makes uses of <span class="hardNobr">RegexKit<i class="rk">Lites</i></span> features. If your project has grown beyond this, you&#39;ve probably already organized a common <span class="hardNobr">"master"</span> header to include to capture headers that are required by nearly all source files already.</p></li>

</ol>

<h4 id="AddingRegexKitLitetoyourProject_AddingRegexKitLiteusingtheShell">Adding <span class="rkl">RegexKit<i>Lite</i></span> using the Shell</h4>

<p>Using <span class="rkl">RegexKit<i>Lite</i></span> from the shell is also easy.  Again, you need to add the header <span class="code hardNobr">#import</span> to the appropriate source files.  Then, to link to the ICU library, you typically only need to add <span class="code hardNobr">-licucore</span>, just as you would any other library.  Consider the following example:</p>

<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">link_example.m</span></span></div>#import &lt;Foundation/NSObjCRuntime.h&gt;
#import &lt;Foundation/NSAutoreleasePool.h&gt;
#import &quot;RegexKitLite.h&quot;

int main(int argc, char *argv[]) {
  NSAutoreleasePool *pool = [<span class="hardNobr">[NSAutoreleasePool alloc]</span> <span class="hardNobr">init];</span>

  // <span class="comment">Copyright COPYRIGHT_SIGN APPROXIMATELY_EQUAL_TO 2008</span>
  // <span class="comment">Copyright \u00a9 \u2245 2008</span>

  char     *utf8CString =  <span class="hardNobr">&quot;Copyright \xC2\xA9 \xE2\x89\x85 2008&quot;;</span>
  NSString *regexString = @&quot;Copyright (.*) (\\d+)&quot;;

  NSString *subjectString = [NSString <span class="hardNobr">stringWithUTF8String:utf8CString];</span>
  NSString *matchedString = [subjectString <span class="hardNobr">stringByMatching:regexString</span> <span class="hardNobr">capture:1L];</span>

  NSLog(@&quot;subject: \&quot;%@\&quot;&quot;, subjectString);
  NSLog(@&quot;matched: \&quot;%@\&quot;&quot;, matchedString);

  [pool release];
  return(0);
}</div>

<p>Compiled and run from the shell:</p>

<div class="box shell"><span class="shellOutput">shell% </span><span class="userInput">cd examples<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">shell% </span><span class="userInput">gcc -g -I.. -o link_example link_example.m <span class="hardNobr">../RegexKitLite.m</span> <span class="hardNobr">-framework Foundation</span> <span class="hardNobr">-licucore<span class="return" title="Return key">&crarr;</span></span></span>
<span class="shellOutput">shell% </span><span class="userInput">./link_example<span class="return" title="Return key">&crarr;</span></span>
<span class="shellOutput">2008-03-14 03:52:51.187 test[15283:807] subject: &quot;Copyright &copy; &cong; 2008&quot;
2008-03-14 03:52:51.269 test[15283:807] matched: &quot;&copy; &cong;&quot;
shell% </span><span class="cursor" title="Shell cursor">&#9612;</span></div></div>

<div class="reference printPageBreakAfter">
  <h1 class="reference" id="RegexKitLiteNSStringAdditionsReference"><span class="rkl">RegexKit<i>Lite</i></span> NSString Additions Reference</h1>  
  <div class="box classSpecs hasRows zebraRows">
    <div class="row odd"><span class="cell left hardNobr">Extends by category</span><span class="cell right lastCell"><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/index.html">NSString</a>, <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSMutableString_Class/index.html">NSMutableString</a></span></div>
    <div class="row even regexKitVersion"><span class="cell left hardNobr"><span class="rkl">RegexKit<i>Lite</i></span></span><span class="cell right lastCell"><span class="version">4.0</span></span></div>
    <div class="row odd"><span class="cell left hardNobr">Declared in</span><ul class="cell right lastCell"><li>RegexKitLite.h</li></ul></div>
    <div class="row even lastRow"><span class="cell left hardNobr">Companion guides</span>
      <ul class="cell right lastCell">
	<li><a href="http://userguide.icu-project.org/strings/regexp" class="printURL">ICU User Guide - Regular Expressions</a></li>
    </ul></div>
  </div>
  

<h2>Overview</h2>

<p><span class="rkl">RegexKit<i>Lite</i></span> is not meant to be a full featured regular expression framework. Because of this, it provides only the basic primitives needed to create additional functionality. It is ideal for developers who:</p>

<ul class="square">
<li>Developing applications for the iPhone.</li>
<li>Have modest regular expression needs.</li>
<li>Require a very small footprint.</li>
<li>Unable or unwilling to add additional, external frameworks.</li>
<li>Deal predominantly in <span class="code hardNobr">UTF-16</span> encoded Unicode strings.</li>
<li>Require the enhanced word breaking functionality provided by the ICU library.</li>
</ul>

<p><span class="rkl">RegexKit<i>Lite</i></span> consists of only two files, the header file <span class="file">RegexKitLite.h</span> and <span class="file">RegexKitLite.m</span>.  The only other requirement is to link with the ICU library that comes with <span class="hardNobr">Mac OS X.</span>  No new classes are created, all functionality is provided as a category extension to the <span class="code">NSString</span> and <span class="code">NSMutableString</span> classes.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#RegexKitLiteGuide" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> Guide</a></li>
    <li><a href="#ICUSyntax_ICURegularExpressionSyntax" class="section-link">ICU Regular Expression Syntax</a></li>
    <li><a href="#AddingRegexKitLitetoyourProject" class="section-link">Adding <span class="rkl">RegexKit<i>Lite</i></span> to your Project</a></li>
    <li><a href="#LicenseInformation" class="section-link">License Information</a></li>
    <li><a href="http://regexkit.sourceforge.net/" class="section-link printURL">RegexKit Framework</a></li>
    <li><a href="http://site.icu-project.org/" class="section-link printURL">International Components for Unicode</a></li>
    <li><a href="http://www.unicode.org/" class="section-link printURL">Unicode Home Page</a></li>
  </ul>
</div>

<h3 id="NSString_RegexKitLiteAdditions__CompileTimePreprocessorTunables">Compile Time Preprocessor Tunables</h3>

<p>The settings listed below are implemented using the C Preprocessor.  Some of the setting are simple boolean <span class="code">enabled</span> or <span class="code">disabled</span> settings, while others specify a value, such as the number of cached compiled regular expressions.  There are several ways to alter these settings, but if you are not familiar with this style of compile time configuration settings and how to alter them using the C Preprocessor, it is recommended that you use the default values provided.</p>

<table class="standard cppTunables" summary="Compile Time Preprocessor Tunables">
<tr><th>Setting</th><th>Default</th><th>Description</th></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">NS_&#8203;BLOCK_&#8203;ASSERTIONS</span><span class="cpp_flag softNobr tbrOff">NS_BLOCK_ASSERTIONS</span></span></td><td><i>n/a</i></td><td><span class="rkl">RegexKit<i>Lite</i></span> contains a number of extra run-time assertion checks that can be disabled with this flag.  The standard <span class="file">NSException.h</span> assertion macros are not used because of the multithreading lock.  This flag is typically set for <span class="context-menu">Release</span> style builds where the additional error checking is no longer necessary.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;APPEND_&#8203;TO_&#8203;ICU_&#8203;FUNCTIONS</span><span class="cpp_flag softNobr tbrOff">RKL_APPEND_TO_ICU_FUNCTIONS</span></span></td><td><i>None</i></td><td>This flag is useful if you are supplying your own version of the ICU library. When set, this preprocessor define causes the ICU functions used by <span class="rkl">RegexKit<i>Lite</i></span> to have the value of <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;APPEND_&#8203;TO_&#8203;ICU_&#8203;FUNCTIONS</span><span class="cpp_flag softNobr tbrOff">RKL_APPEND_TO_ICU_FUNCTIONS</span></span> appended to them. For example, if <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;APPEND_&#8203;TO_&#8203;ICU_&#8203;FUNCTIONS</span><span class="cpp_flag softNobr tbrOff">RKL_APPEND_TO_ICU_FUNCTIONS</span></span> is set to <span class="code">_4_0</span> <span class="softNobr">(i.e., <span><span class="consoleText tbrOn">-DRKL_&#8203;APPEND_&#8203;TO_&#8203;ICU_&#8203;FUNCTIONS=_4_0</span><span class="consoleText tbrOff">-DRKL_APPEND_TO_ICU_FUNCTIONS=_4_0</span></span>),</span> it would cause <span class="code">uregex_find()</span> to become <span class="code">uregex_find_4_0()</span>.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;BLOCKS</span><span class="cpp_flag softNobr tbrOff">RKL_BLOCKS</span></span></td><td><i>Automatic</i></td><td> Enables blocks support. This feature is automatically enabled if <span><span class="cpp_flag softNobr tbrOn">NS_&#8203;BLOCKS_&#8203;AVAILABLE</span><span class="cpp_flag softNobr tbrOff">NS_BLOCKS_AVAILABLE</span></span> is set to <span class="code">1</span>, which is typically set if support for blocks is appropriate.  At the time of this writing, this typically means that the Xcode setting for the minimum version of <span class="hardNobr">Mac OS X</span> supported must be <span class="hardNobr">10.6</span>. This feature may be explicitly disabled under all circumstances by setting its value to <span class="code">0</span>, or alternatively it can be explicitly enabled under all circumstances by setting its value to <span class="code">1</span>.  The behavior is undefined if <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;BLOCKS</span><span class="cpp_flag softNobr tbrOff">RKL_BLOCKS</span></span> is set to <span class="code">1</span> and the compiler does not support the blocks language extension or if the run-time does not support blocks.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;CACHE_&#8203;SIZE</span><span class="cpp_flag softNobr tbrOff">RKL_CACHE_SIZE</span></span></td><td><span class="code">13</span></td>
<td><span class="rkl">RegexKit<i>Lite</i></span> uses a 4-way set associative cache and <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;CACHE_&#8203;SIZE</span><span class="cpp_flag softNobr tbrOff">RKL_CACHE_SIZE</span></span> controls the number of sets in the cache.  The total number of compiled regular expressions that can be cached is <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;CACHE_&#8203;SIZE</span><span class="cpp_flag softNobr tbrOff">RKL_CACHE_SIZE</span></span> * <span class="code">4</span>, for a default value of <span class="code">52</span>.  <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;CACHE_&#8203;SIZE</span><span class="cpp_flag softNobr tbrOff">RKL_CACHE_SIZE</span></span> should always be a prime number to maximize the use of the cache.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;DTRACE</span><span class="cpp_flag softNobr tbrOff">RKL_DTRACE</span></span></td><td><i>Disabled</i></td><td>This preprocessor define controls whether or not <span class="rkl">RegexKit<i>Lite</i></span> provider DTrace probe points are enabled.  This feature may be explicitly disabled under all circumstances by setting its value to <span class="code">0</span>.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;FAST_&#8203;MUTABLE_&#8203;CHECK</span><span class="cpp_flag softNobr tbrOff">RKL_FAST_MUTABLE_CHECK</span></span></td><td><i>Disabled</i></td><td>Enables the use of the undocumented, private <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> <span class="code hardNobr">__CFStringIsMutable()</span> function to determine if the string to be searched is immutable.  This can significantly increase the number of matches per second that can be performed on immutable strings since a number of mutation checks can be safely skipped.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;FIXED_&#8203;LENGTH</span><span class="cpp_flag softNobr tbrOff">RKL_FIXED_LENGTH</span></span></td><td><span class="code">2048</span></td><td>Sets the size of the fixed length <span class="code hardNobr">UTF-16</span> conversion cache buffer.  Strings that need to be converted to <span class="code">UTF-16</span> that have a length less than this size will use the fixed length conversion cache.  Using a fixed sized buffer for all small strings means less <span class="code">malloc()</span> overhead, heap fragmentation, and reduces the chances of a memory leak occurring.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;METHOD_&#8203;PREPEND</span><span class="cpp_flag softNobr tbrOff">RKL_METHOD_PREPEND</span></span></td><td><i>None</i></td><td>When set, this preprocessor define causes the <span class="rkl">RegexKit<i>Lite</i></span> methods defined in <span class="file">RegexKitLite.h</span> to have the value of <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;METHOD_&#8203;PREPEND</span><span class="cpp_flag softNobr tbrOff">RKL_METHOD_PREPEND</span></span> prepended to them.  For example, if <span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;METHOD_&#8203;PREPEND</span><span class="cpp_flag softNobr tbrOff">RKL_METHOD_PREPEND</span></span> is set to <span class="code">xyz_</span> <span class="softNobr">(i.e., <span><span class="consoleText tbrOn">-DRKL_&#8203;METHOD_&#8203;PREPEND=xyz_</span><span class="consoleText tbrOff">-DRKL_METHOD_PREPEND=xyz_</span></span>),</span> it would cause <a href="#NSString_RegexKitLiteAdditions__.clearStringCache" class="code">clearStringCache</a> to become <span class="code">xyz_clearStringCache</span>.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;REGISTER_&#8203;FOR_&#8203;IPHONE_&#8203;LOWMEM_&#8203;NOTIFICATIONS</span><span class="cpp_flag softNobr tbrOff">RKL_REGISTER_FOR_IPHONE_LOWMEM_NOTIFICATIONS</span></span></td><td><i>Automatic</i></td><td>This preprocessor define controls whether or not extra code is included that attempts to automatically register with the <span class="code">NSNotificationCenter</span> for the <span><a href="http://developer.apple.com/iphone/library/documentation/UIKit/Reference/UIApplication_Class/Reference/Reference.html#//apple_ref/c/data/UIApplicationDidReceiveMemoryWarningNotification" class="code tbrOn">UIApplication&#8203;DidReceive&#8203;MemoryWarning&#8203;Notification</a><a href="http://developer.apple.com/iphone/library/documentation/UIKit/Reference/UIApplication_Class/Reference/Reference.html#//apple_ref/c/data/UIApplicationDidReceiveMemoryWarningNotification" class="code tbrOff">UIApplicationDidReceiveMemoryWarningNotification</a></span> notification.  This feature is automatically enabled if it can be determined at compile time that the iPhone is being targeted.  This feature may be explicitly disabled under all circumstances by setting its value to <span class="code">0</span>.</td></tr>
<tr><td><span><span class="cpp_flag softNobr tbrOn">RKL_&#8203;STACK_&#8203;LIMIT</span><span class="cpp_flag softNobr tbrOff">RKL_STACK_LIMIT</span></span></td><td><span class="code">131072</span></td><td>The maximum amount of stack space that will be used before switching to heap based allocations.  This can be useful for multithreading programs where the stack size of secondary threads is much smaller than the main thread.</td></tr>
</table>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Assertions/Tasks/AssertMacros.html" class="section-link printURL_small">Assertions and Logging - Using the Assertion Macros</a></li>
  </ul>
</div>

<h4>Fast Mutable Checks</h4>

<p>Setting <span class="cpp_flag">RKL_FAST_MUTABLE_CHECK</span> allows <span class="rkl">RegexKit<i>Lite</i></span> to quickly check if a string to search is immutable or not.  Every call to <span class="rkl">RegexKit<i>Lite</i></span> requires checking a strings <span class="code">hash</span> and <span class="code">length</span> values to guard against a string mutating and using invalid cached data.  If the same string is searched repeatedly and it is immutable, these checks aren&#39;t necessary since the string can never change while in use.  While these checks are fairly quick, it can add approximately 15 to 20 percent of extra overhead, and not performing the checks is always faster.</p>

<p>Since checking a strings mutability requires calling an undocumented, private <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> function, <span class="rkl">RegexKit<i>Lite</i></span> takes extra precautions and does not use the function directly.  Instead, an internal, local stub function is created and called to determine if a string is mutable.  The first time this function is called, <span class="rkl">RegexKit<i>Lite</i></span> uses <span class="code hardNobr">dlsym()</span> to look up the address of the <span class="code hardNobr">__CFStringIsMutable()</span> function.  If the function is found, <span class="rkl">RegexKit<i>Lite</i></span> will use it from that point on to determine if a string is immutable. However, if the function is not found, <span class="rkl">RegexKit<i>Lite</i></span> has no way to determine if a string is mutable or not, so it assumes the worst case that all strings are potentially mutable.  This means that the private <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> <span class="code hardNobr">__CFStringIsMutable()</span> function can go away at any time and <span class="rkl">RegexKit<i>Lite</i></span> will continue to work, although with slightly less performance.</p>

<p>This feature is disabled by default, but should be fairly safe to enable due to the extra precautions that are taken.  If this feature is enabled and the <span class="code hardNobr">__CFStringIsMutable()</span> function is not found for some reason, <span class="rkl">RegexKit<i>Lite</i></span> falls back to its default behavior which is the same as if this feature was not enabled.</p>

<h4>iPhone Low Memory Notifications</h4>

<p>The <span class="cpp_flag">RKL_REGISTER_FOR_IPHONE_LOWMEM_NOTIFICATIONS</span> preprocessor define controls whether or not extra code is compiled in that automatically registers for the iPhone UIKit <a href="http://developer.apple.com/iphone/library/documentation/UIKit/Reference/UIApplication_Class/Reference/Reference.html#//apple_ref/c/data/UIApplicationDidReceiveMemoryWarningNotification" class="code">UIApplicationDidReceiveMemoryWarningNotification</a> notification.  When enabled, an initialization function tagged with <span class="code">__attribute__((constructor))</span> is executed by the linker at load time which causes <span class="rkl">RegexKit<i>Lite</i></span> to check if the low memory notification symbol is available.  If the symbol is present then <span class="rkl">RegexKit<i>Lite</i></span> registers to receive the notification.  When the notification is received, <span class="rkl">RegexKit<i>Lite</i></span> will automatically call <a href="#NSString_RegexKitLiteAdditions__.clearStringCache" class="code">clearStringCache</a> to flush the caches and return the memory used to hold any cached compiled regular expressions.</p>

<p>This feature is normally automatically enabled if it can be determined at compile time that the iPhone is being targeted.  This feature is safe to enable even if the target is Mac OS X for the desktop.  It can also be explicitly disabled, even when targeting the iPhone, by setting <span class="cpp_flag">RKL_REGISTER_FOR_IPHONE_LOWMEM_NOTIFICATIONS</span> to <span class="code">0</span> <span class="hardNobr">(i.e., <span class="consoleText">-DRKL_REGISTER_FOR_IPHONE_LOWMEM_NOTIFICATIONS=0</span>).</span></p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://developer.apple.com/iphone/library/documentation/Performance/Conceptual/ManagingMemory/Articles/MemoryAlloc.html#//apple_ref/doc/uid/20001881-SW1" class="section-link printURL_small">Memory Usage Performance Guidelines - Responding to Low-Memory Warnings in iPhone OS</a></li>
  </ul>
</div>

<h4>Using <span class="rkl">RegexKit<i>Lite</i></span> with a Custom ICU Build</h4>

<p>The details of building and linking to a custom build of ICU will not be covered here.  ICU is a very large and complex library that can be configured and packaged in countless ways.  Building and linking your application to a custom build of ICU is <i><b>non&#8209;trivial</b></i>.  Apple provides the full source to the version of ICU that they supply with <span class="hardNobr">Mac OS X.</span>  At the time of this writing, the latest version available was for <span class="hardNobr">Mac OS X 10.6.2&mdash;</span> <a href="http://www.opensource.apple.com/tarballs/ICU/ICU-400.38.tar.gz" class="file printURL">ICU-400.38.tar.gz</a>.</p>

<p><span class="rkl">RegexKit<i>Lite</i></span> provides the <span class="cpp_flag">RKL_APPEND_TO_ICU_FUNCTIONS</span> pre-processor define if you would like to use <span class="rkl">RegexKit<i>Lite</i></span> with a custom ICU build that you supply.  A custom version of ICU will typically have the ICU version appended to all of its functions, and <span class="cpp_flag">RKL_APPEND_TO_ICU_FUNCTIONS</span> allows you to append that version to the ICU functions that <span class="rkl">RegexKit<i>Lite</i></span> calls.  For example, passing <span class="hardNobr consoleText">-DRKL_APPEND_TO_ICU_FUNCTIONS=_4_0</span> to <span class="consoleText">gcc</span> would cause the ICU function <span class="hardNobr code">uregex_find()</span> used by <span class="rkl">RegexKit<i>Lite</i></span> to be called as <span class="hardNobr code">uregex_find_4_0()</span>.</p>

<h3 id="NSString_RegexKitLiteAdditions__Xcode3IntegratedDocumentation">Xcode 3 Integrated Documentation</h3>

<p>This documentation is available in the Xcode DocSet format at the following URL:</p>

<p class="indent"><span class="code">feed://regexkit.sourceforge.net/RegexKitLiteDocSets.atom</span></p>

<p>For Xcode &lt; 3.2, select <span class="context-menu">Help </span><span class="submenuArrow">&#9658;</span><span class="context-menu"> Documentation</span>. Then, in the lower left hand corner of the documentation window, there should be a gear icon with a drop down menu indicator which you should select and choose <span class="context-menu">New Subscription&hellip;</span> and enter the DocSet URL.</p>

<p>For Xcode &ge; 3.2, select <span class="context-menu">Xcode </span><span class="submenuArrow">&#9658;</span><span class="context-menu"> Preferences&hellip;</span>.
Then select the <span class="context-menu">Documentation</span> preference group, typically the right most group, and press <span class="context-menu">Add Documentation Set Publisher&hellip;</span> and enter the DocSet URL.</p>


<p>Once you have added the URL, a new group should appear, inside which will be the <span class="rkl">RegexKit<i>Lite</i></span> documentation with a <span class="xcode-button">Get</span> button.  Click on the <span class="xcode-button">Get</span> button and follow the prompts.</p>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<p>Xcode will ask you to enter an administrators password to install the documentation, which is explained <a href="http://developer.apple.com/mac/library/documentation/DeveloperTools/Conceptual/Documentation_Sets/070-Acquiring_Documentation_Sets_Through_Web_Feeds/acquiring_docsets.html#//apple_ref/doc/uid/TP40005266-CH10-SW9" class="printURL_small">here</a>.</p>
</div></div></div></div>

<h3 id="NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings">Cached Information and Mutable Strings</h3>

<p>While <span class="rkl">RegexKit<i>Lite</i></span> takes steps to ensure that the information it has cached is valid for the strings it searches, there exists the possibility that out of date cached information may be used when searching mutable strings.  For each compiled regular expression, <span class="rkl">RegexKit<i>Lite</i></span> caches the following information about the last <span class="code">NSString</span> that was searched:</p>

<ul class="square">
<li>The strings <span class="code">length</span>, <span class="code">hash</span> value, and the pointer to the <span class="code">NSString</span> object.</li>
<li>The pointer to the <span class="code hardNobr">UTF-16</span> buffer that contains the contents of the string, which may be an internal buffer if the string required conversion.</li>
<li>The <span class="code">NSRange</span> used for the <span class="code">inRange:</span> parameter for the last search, and the <span class="code">NSRange</span> result for capture <span class="code">0</span> of that search.</li>
</ul>

<p>An ICU compiled regular expression must be <span class="hardNobr">&quot;set&quot;</span> to the text to be searched.  Before a compiled regular expression is used, the pointer to the string object to search, its <span class="code">hash</span>, <span class="code">length</span>, and the pointer to the <span class="code">UTF-16</span> buffer is compared with the values that the compiled regular expression was last <span class="hardNobr">&quot;set&quot;</span> to.  If any of these values are different, the compiled regular expression is reset and <span class="hardNobr">&quot;set&quot;</span> to the new string.</p>

<p>If a <span class="code">NSMutableString</span> is mutated between two uses of the same compiled regular expression and its <span class="code">hash</span>, <span class="code">length</span>, or <span class="code hardNobr">UTF-16</span> buffer changes between uses, <span class="rkl">RegexKit<i>Lite</i></span> will automatically reset the compiled regular expression with the new values of the mutated string.  The results returned will correctly reflect the mutations that have taken place between searches.</p>

<p>It is possible that the mutations to a string can go undetected, however.  If the mutation keeps the <span class="code">length</span> the same, then the only way a change can be detected is if the strings <span class="code">hash</span> value changes.  For most mutations the <span class="code">hash</span> value will change, but it is possible for two different strings to share the same <span class="code">hash</span>.  This is known as a <i>hash collision</i>.  Should this happen, the results returned by <span class="rkl">RegexKit<i>Lite</i></span> may not be correct.</p>

<p>Therefore, if you are using <span class="rkl">RegexKit<i>Lite</i></span> to search <span class="code">NSMutableString</span> objects, and those strings may have mutated in such a way that <span class="rkl">RegexKit<i>Lite</i></span> is unable to detect that the string has changed, you must manually clear the internal cache to ensure that the results accurately reflect the mutations.  To clear the cached information for a specific string you send the instance a <a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="code">flushCachedRegexData</a> message:</p>

<div class="box sourcecode">NSMutableString *aMutableString; // <span class="comment">Assumed to be valid.</span>
[aMutableString flushCachedRegexData];</div>

<p>To clear all of the cached information in <span class="rkl">RegexKit<i>Lite</i></span>, which includes all the cached compiled regular expressions along with any cached information and <span class="hardNobr code">UTF-16</span> conversions for strings that have been searched, you use the following class method:</p>

<div class="box sourcecode">[NSString clearStringCache];</div>

<div class="box warning"><div class="table"><div class="row"><div class="label cell">Warning:</div><div class="message cell">
<p>When searching <span class="code">NSMutableString</span> objects that have mutated between searches, failure to clear the cache may result in undefined behavior.  Use <a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="code">flushCachedRegexData</a> to selectively clear the cached information about a <span class="code">NSMutableString</span> object.</p>
</div></div></div></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__.clearStringCache" class="code">+ clearStringCache</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="code">- flushCachedRegexData</a></li>
  </ul>
</div>

<h3 id="RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods">Block-based Enumeration Methods</h3>


<p>The <span class="rkl">RegexKit<i>Lite</i></span> Block-based enumeration methods are modeled after their <span class="code">NSString</span> counterparts.  There are a few differences, however.</p>

<ul class="square highlights">
  <li><span class="rkl">RegexKit<i>Lite</i></span> does not support mutating a <span class="code">NSMutableString</span> object while it is under going Block-based enumeration.</li>
  <li>There is no support for concurrent enumeration.</li>
</ul>

<p>While <span class="rkl">RegexKit<i>Lite</i></span> may not support mutating a <span class="code">NSMutableString</span> during Block-based enumeration, it does provide the means to create a new string from the <span class="code">NSString</span> object returned by the block used to enumerate the matches in a string, and in the case of <span class="code">NSMutableString</span>, to replace the contents of that <span class="code">NSMutableString</span> with the modified string at the end of the enumeration.  This functionality is available via the following methods:</p>

<ul class="square highlights">
  <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:" class="code">- stringByReplacingOccurrencesOfRegex:usingBlock:</a> (<span class="code">NSString</span>)</li>
  <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:" class="code">- replaceOccurrencesOfRegex:usingBlock:</a> (<span class="code">NSMutableString</span>)</li>
</ul>

<h4>Exception to the Cocoa Memory Management Rules for Block-based Enumeration</h4>

<p>The standard <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html" class="section-link">Cocoa Memory Management Rules</a> specify that objects returned by a method, or in this case the objects passed to a Block, remain valid throughout the scope of the calling method.  Due to the potentially large volume of temporary strings that are created during a Block-based enumeration, <span class="rkl">RegexKit<i>Lite</i></span> makes an exception to this rule&ndash; the strings passed to a Block via <span class="argument">capturedStrings</span><span class="code">[]</span> are valid only until the closing brace of the Block:</p>

<div class="box sourcecode">[searchString enumerateStringsMatchedByRegex:regex
                                  usingBlock:
 ^(NSInteger captureCount,
   NSString * const capturedStrings,
   const NSRange capturedRanges[captureCount],
   volatile BOOL * const stop) {
   // <span class="comment">Block code.</span>
 } /* <span class="comment">&lt;- capturedStrings[] is valid only up to this point.</span> */ ];</div>

<p>If you need to refer to a string past the closing brace of the Block, you need to send that string a <span class="code">retain</span> message.  Of course, it is not always necessary to explicitly send a <span class="argument">capturedStrings</span><span class="code">[]</span> string a <span class="code">retain</span> message when you need it to exist past the closing brace of a Block&ndash; adding a <span class="argument">capturedStrings</span><span class="code">[]</span> string to a <span class="code">NSMutableDictionary</span> will send the string a <span class="code">retain</span> as a side effect of adding it to the dictionary.</p>

<p>Memory management during <span class="rkl">RegexKit<i>Lite</i></span> Block-based enumeration is conceptually similar to the following pseudo-code:</p>

<div class="box sourcecode">NSInteger captureCount = [regex captureCount];

while(moreMatches) {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BOOL      stop = NO;
  NSRange   capturedRanges[captureCount];
  NSString *capturedStrings[captureCount];

  for(capture = 0L; capture &lt; captureCount; capture++) {
    capturedRanges[capture]  = [searchString rangeOfRegex:regex capture:capture];
    capturedStrings[capture] = [searchString stringByMatching:regex capture:capture];
  }

  // <span class="comment">The following line represents the execution of the user supplied Block.</span>
  enumerationBlock(captureCount, capturedStrings, capturedRanges, &amp;stop);
  // <span class="comment">... and this represents when the user supplied Block has finished / returned.</span>

  [pool release]; // <span class="comment">capturedStrings[] are sent a release at this point.</span>
  if(stop != NO) { break; }
}</div>

<p>While conceptually and behaviorally similar, it is important to note that <span class="rkl">RegexKit<i>Lite</i></span> does not actually use or create autorelease pools when performing Block-based enumeration.  Instead, a <span class="code">CFMutableArray</span> object is used to accumulate the temporary string objects during an iteration, and at the start of an iteration, any previously accumulated temporary string objects are removed from the array.</p>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
    <li><a href="#RegularExpressionEnumerationOptions" class="section-link">Regular Expression Enumeration Options</a></li>
  </ul>
</div>

<h3>Usage Notes</h3>

<h4>Convenience Methods</h4>

<p>For convenience methods where an argument is not present, the default value used is given below.</p>

<table class="standard">
<tr><th>Argument</th><th>Default Value</th></tr>
<tr><td><span class="code">capture:</span></td><td><span class="code">0</span></td></tr>
<tr><td><span class="code">options:</span></td><td><a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a></td></tr>
<tr><td><span class="code">range:</span></td><td>The entire range of the receiver.</td></tr>
<tr><td><span class="code">enumerationOptions:</span></td><td><a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationNoOptions" class="code">RKLRegexEnumerationNoOptions</a></td></tr>
</table>

<h4>Exceptions Raised</h4>

<p>Methods will raise an exception if their arguments are invalid, such as passing <span class="code">NULL</span> for a required parameter.  An invalid regular expression or <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> parameter will not raise an exception.  Instead, a <span class="code">NSError</span> object with information about the error will be created and returned via the address given with the optional <span class="argument">error</span> argument.  If information about the problem is not required, <span class="argument">error</span> may be <span class="code">NULL</span>.  For convenience methods that do not have an <span class="argument">error</span> argument, the primary method is invoked with <span class="code">NULL</span> passed as the argument for <span class="argument">error</span>.</p>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
Methods raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSInvalidArgumentException" class="code">NSInvalidArgumentException</a> if <span class="argument">regex</span> is <span class="code">NULL</span>, or if <span class="hardNobr"><span class="argument">capture</span> &lt; <span class="code">0</span></span> or is not valid for <span class="argument">regex</span>.
</div></div></div></div>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
Methods raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSRangeException" class="code">NSRangeException</a> if <span class="argument">range</span> exceeds the bounds of the receiver.
</div></div></div></div>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
Methods raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSRangeException" class="code">NSRangeException</a> if the receivers length exceeds the maximum value that can be represented by a signed <span class="hardNobr">32-bit</span> integer, even on <span class="hardNobr">64-bit</span> architectures.
</div></div></div></div>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Search and replace methods raise <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <span class="argument">replacement</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression <span class="argument">regex</span>.</div></div></div></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
  </ul>
</div>

<h2>Tasks</h2>

<div class="tasks">
  <div class="header">DTrace Probe Points</div>
  <ul>
    <li><a href="#DTrace_RegexKitLiteProbePoints__compiledRegexCache" title="This probe point fires each time the compiled regular expression cache is accessed." class="code">RegexKitLite:::compiledRegexCache</a></li>
    <li><a href="#DTrace_RegexKitLiteProbePoints__utf16ConversionCache" title="This probe point fires each time the UTF-16 conversion cache is accessed." class="code">RegexKitLite:::utf16ConversionCache</a></li>
  </ul>
</div>

<div class="tasks">
  <div class="header">Clearing Cached Information</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__.clearStringCache" title="Clears the cached information about strings." class="code">+ clearStringCache</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" title="Clears any cached information about the receiver." class="code">- flushCachedRegexData</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Determining the Number of Captures</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__.captureCountForRegex:" title="Returns the number of captures that regex contains." class="code">+ captureCountForRegex:</a> <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</span></li>
    <li><a href="#NSString_RegexKitLiteAdditions__.captureCountForRegex:options:error:" title="Returns the number of captures that regex contains." class="code">+ captureCountForRegex:options:error:</a> <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</span></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-captureCount" title="Returns the number of captures that regex contains." class="code">- captureCount</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:" title="Returns the number of captures that regex contains." class="code">- captureCountWithOptions:error:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Finding all Captures of all Matches</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:" title="Returns an array containing all the matches from the receiver that were matched by the regular expression regex. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression." class="code">- arrayOfCaptureComponentsMatchedByRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:" title="Returns an array containing all the matches from the receiver that were matched by the regular expression regex within range. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression." class="code">- arrayOfCaptureComponentsMatchedByRegex:range:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:" title="Returns an array containing all the matches from the receiver that were matched by the regular expression regex within range using options. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression." class="code">- arrayOfCaptureComponentsMatchedByRegex:options:range:error:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Getting all the Captures of a Match</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:" title="Returns an array containing the substrings matched by each capture group present in regex for the first match of regex in the receiver." class="code">- captureComponentsMatchedByRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:" title="Returns an array containing the substrings matched by each capture group present in regex for the first match of regex within range of the receiver." class="code">- captureComponentsMatchedByRegex:range:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:" title="Returns an array containing the substrings matched by each capture group present in regex for the first match of regex within range of the receiver using options." class="code">- captureComponentsMatchedByRegex:options:range:error:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Finding all Matches</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" title="Returns a NSArray containing all the substrings from the receiver that were matched by the regular expression regex." class="code">- componentsMatchedByRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:" title="Returns a NSArray containing all the substrings from the receiver that were matched by capture number capture from the regular expression regex." class="code">- componentsMatchedByRegex:capture:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:" title="Returns a NSArray containing all the substrings from the receiver that were matched by the regular expression regex within range." class="code">- componentsMatchedByRegex:range:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:" title="Returns a NSArray containing all the substrings from the receiver that were matched by the regular expression regex within range using options." class="code">- componentsMatchedByRegex:options:range:capture:error:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:" title="Enumerates the matches in the receiver by the regular expression regex and executes block for each match found." class="code">- enumerateStringsMatchedByRegex:usingBlock:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:" title="Enumerates the matches in the receiver by the regular expression regex within range using options and executes block using enumerationOptions for each match found." class="code">- enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Dividing Strings</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" title="Returns a NSArray containing substrings of the receiver that have been divided by the regular expression regex." class="code">- componentsSeparatedByRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:" title="Returns a NSArray containing substrings within range of the receiver that have been divided by the regular expression regex." class="code">- componentsSeparatedByRegex:range:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:" title="Returns a NSArray containing substrings within range of the receiver that have been divided by the regular expression regex using options." class="code">- componentsSeparatedByRegex:options:range:error:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:" title="Enumerates the strings of the receiver that have been divided by the regular expression regex and executes block for each divided string." class="code">- enumerateStringsSeparatedByRegex:usingBlock:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:" title="Enumerates the strings of the receiver that have been divided by the regular expression regex within range using options and executes block using enumerationOptions for each divided string." class="code">- enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Identifying Matches</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:" title="Returns a Boolean value that indicates whether the receiver is matched by regex." class="code">- isMatchedByRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:" title="Returns a Boolean value that indicates whether the receiver is matched by regex within range." class="code">- isMatchedByRegex:inRange:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:" title="Returns a Boolean value that indicates whether the receiver is matched by regex within range." class="code">- isMatchedByRegex:options:inRange:error:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Determining if a Regular Expression is Valid</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-isRegexValid" title="Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid." class="code">- isRegexValid</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-isRegexValidWithOptions:error:" title="Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid using options." class="code">- isRegexValidWithOptions:error:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Determining the Range of a Match</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:" title="Returns the range for the first match of regex in the receiver." class="code">- rangeOfRegex:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:" title="Returns the range of capture number capture for the first match of regex in the receiver." class="code">- rangeOfRegex:capture:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:" title="Returns the range for the first match of regex within range of the receiver." class="code">- rangeOfRegex:inRange:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:" title="Returns the range of capture number capture for the first match of regex within range of the receiver." class="code">- rangeOfRegex:options:inRange:capture:error:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Modifying Mutable Strings</div>
  <ul>
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" title="Replaces all occurrences of the regular expression regex with the contents of replacement string after performing capture group substitutions, returning the number of replacements made." class="code">- replaceOccurrencesOfRegex:withString:</a></li>
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:" title="Replaces all occurrences of the regular expression regex within range with the contents of replacement string after performing capture group substitutions, returning the number of replacements made." class="code">- replaceOccurrencesOfRegex:withString:range:</a></li>
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:" title="Replaces all occurrences of the regular expression regex using options within range with the contents of replacement string after performing capture group substitutions, returning the number of replacements made." class="code">- replaceOccurrencesOfRegex:withString:options:range:error:</a></li>
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:" title="Enumerates the matches in the receiver by the regular expression regex and executes block for each match found. Replaces the characters that were matched with the contents of the string returned by block, returning the number of replacements made." class="code">- replaceOccurrencesOfRegex:usingBlock:</a></li>
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:" title="Enumerates the matches in the receiver by the regular expression regex within range using options and executes block using enumerationOptions for each match found. Replaces the characters that were matched with the contents of the string returned by block, returning the number of replacements made." class="code">- replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Creating Temporary Strings from a Match</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:" title="Returns a string created from the characters of the receiver that are in the range of the first match of regex." class="code">- stringByMatching:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:capture:" title="Returns a string created from the characters of the receiver that are in the range of the first match of regex for capture." class="code">- stringByMatching:capture:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:inRange:" title="Returns a string created from the characters of the receiver that are in the range of the first match of regex within range of the receiver." class="code">- stringByMatching:inRange:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:" title="Returns a string created from the characters of the receiver that are in the range of the first match of regex using options within range of the receiver for capture." class="code">- stringByMatching:options:inRange:capture:error:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Replacing Substrings</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" title="Returns a string created from the characters of the receiver in which all matches of the regular expression regex are replaced with the contents of the replacement string after performing capture group substitutions." class="code">- stringByReplacingOccurrencesOfRegex:withString:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:" title="Returns a string created from the characters within range of the receiver in which all matches of the regular expression regex are replaced with the contents of the replacement string after performing capture group substitutions." class="code">- stringByReplacingOccurrencesOfRegex:withString:range:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:" title="Returns a string created from the characters within range of the receiver in which all matches of the regular expression regex using options are replaced with the contents of the replacement string after performing capture group substitutions." class="code softNobr">- stringByReplacingOccurrencesOfRegex:&#8203;withString:options:range:error:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:" title="Enumerates the matches in the receiver by the regular expression regex and executes block for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by block." class="code">- stringByReplacingOccurrencesOfRegex:usingBlock:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:" title="Enumerates the matches in the receiver by the regular expression regex within range using options and executes block using enumerationOptions for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by block." class="code">- stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Creating a Dictionary from a Match</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:" class="code" title="Creates and returns a dictionary containing the matches constructed from the specified set of keys and captures for the first match of regex in the receiver.">- dictionaryByMatchingRegex:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:" class="code" title="Creates and returns a dictionary containing the matches constructed from the specified set of keys and captures for the first match of regex within range of the receiver.">- dictionaryByMatchingRegex:range:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:" class="code" title="Creates and returns a dictionary containing the matches constructed from the specified set of keys and captures for the first match of regex within range of the receiver using options.">- dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:</a></li>
  </ul>
</div>
<div class="tasks">
  <div class="header">Creating a Dictionary from every Match</div>
  <ul>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:" title="Returns an array containing all the matches in the receiver that were matched by the regular expression regex. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of keys and captures." class="code">- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:" title="Returns an array containing all the matches in the receiver that were matched by the regular expression regex within range. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of keys and captures." class="code">- arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:" title="Returns an array containing all the matches in the receiver that were matched by the regular expression regex within range using options. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of keys and captures." class="code">- arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:</a></li>
  </ul>
</div>

<h2>DTrace Probe Points</h2>

<div class="block dtrace">
  <div class="section name softNobr" id="DTrace_RegexKitLiteProbePoints__compiledRegexCache">RegexKitLite:::compiledRegexCache</div>
  <div class="section summary">This probe point fires each time the compiled regular expression cache is accessed.</div>
  <div class="signature"><span class="hardNobr"><span class="function">RegexKitLite:::compiledRegexCache</span>(</span><span class="hardNobr">unsigned long <span class="argument">eventID</span>,</span> <span class="hardNobr">const char *<span class="argument">regexUTF8</span>,</span> <span class="hardNobr">int <span class="argument">options</span>,</span> <span class="hardNobr">int <span class="argument">captures</span>,</span> <span class="hardNobr">int <span class="argument">hitMiss</span>,</span> <span class="hardNobr">int <span class="argument">icuStatusCode</span>,</span> <span class="hardNobr">const char *<span class="argument">icuErrorMessage</span>,</span> <span class="hardNobr">double *<span class="argument">hitRate</span>);</span></div>
  <div class="section parameters"><div class="header">Arguments</div>
    <ul>
      <li>
	<div><span class="code">arg0</span>, <span class="name">eventID</span></div>
        <div class="text">The unique ID for this mutex lock acquisition.</div>
      </li>
      <li>
        <div><span class="code">arg1</span>, <span class="name">regexUTF8</span></div>
	<div class="text">Up to 64 characters of the regular expression encoded in <span class="hardNobr code">UTF-8</span>. Must be copied with <span class="hardNobr code">copyinstr(arg1)</span>.</div>
      </li>
      <li>
        <div><span class="code">arg2</span>, <span class="name">options</span></div>
	<div class="text">The <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> options used.</div>
      </li>
      <li>
        <div><span class="code">arg3</span>, <span class="name">captures</span></div>
        <div class="text">The number of captures present in the regular expression, or <span class="code">-1</span> if there was an error.</div>
      </li>
      <li>
        <div><span class="code">arg4</span>, <span class="name">hitMiss</span></div>
        <div class="text">A boolean value that indicates whether or not this event was a cache hit or not, or <span class="code">-1</span> if there was an error.</div>
      </li>
      <li>
        <div><span class="code">arg5</span>, <span class="name">icuStatusCode</span></div>
        <div class="text">If an error occurs, this contains the error number returned by ICU.</div>
      </li>
      <li>
        <div><span class="code">arg6</span>, <span class="name">icuErrorMessage</span></div>
        <div class="text">If an error occurs, this contains a <span class="hardNobr code">UTF-8</span> encoded string of the ICU error. Must be copied with <span class="hardNobr code">copyinstr(arg6)</span>.</div>
      </li>
      <li>
        <div><span class="code">arg7</span>, <span class="name">hitRate</span></div>
        <div class="text">A pointer to a floating point value, between <span class="hardNobr code">0.0</span> and <span class="hardNobr code">100.0</span>, that represents the effectiveness of cache. Higher is better. Must be copied with <span class="hardNobr code">copyin(arg7, sizeof(double))</span>.</div>
      </li>
    </ul>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>An example of how to copy the <span class="code">double</span> value pointed to by <span class="argument">hitRate</span>:</p>
    <div class="box sourcecode">RegexKitLite*:::compiledRegexCache {
  this-&gt;hitRate = (double *)copyin(arg7, sizeof(double));
  printf(&quot;compiledRegexCache hitRate: %6.2f%%\n&quot;, this-&gt;hitRate);
}</div>

  </div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#DTrace_RegexKitLiteProbePoints__utf16ConversionCache" class="code">RegexKitLite:::utf16ConversionCache</a></li>
      <li><a href="#UsingRegexKitLite_DTrace" class="section-link">Using <span class="rkl">RegexKit<i>Lite</i></span> - DTrace</a></li>
      <li><a href="http://docs.sun.com/app/docs/doc/817-6223" class="section-link printURL">Solaris Dynamic Tracing Guide</a> <a href="http://dlc.sun.com/pdf/817-6223/817-6223.pdf" class="section-link printURL">(as .PDF)</a></li>
    </ul>
  </div>
</div>


<div class="block dtrace">
  <div class="section name softNobr" id="DTrace_RegexKitLiteProbePoints__utf16ConversionCache">RegexKitLite:::utf16ConversionCache</div>
  <div class="section summary">This probe point fires each time the <span class="hardNobr code">UTF-16</span> conversion cache is accessed.</div>
  <div class="signature"><span class="hardNobr"><span class="function">RegexKitLite:::utf16ConversionCache</span>(</span><span class="hardNobr">unsigned long <span class="argument">eventID</span>,</span> <span class="hardNobr">unsigned int <span class="argument">lookupResultFlags</span>,</span> <span class="hardNobr">double *<span class="argument">hitRate</span>,</span> <span class="hardNobr">const void *<span class="argument">string</span>,</span> <span class="hardNobr">unsigned long <span class="argument">NSRange_location</span>,</span> <span class="hardNobr">unsigned long <span class="argument">NSRange_length</span>,</span> <span class="hardNobr">long <span class="argument">length</span>);</span></div>
  <div class="section parameters"><div class="header">Arguments</div>
    <ul>
      <li>
	<div><span class="code">arg0</span>, <span class="name">eventID</span></div>
        <div class="text">The unique ID for this mutex lock acquisition.</div>
      </li>
      <li>
        <div><span class="code">arg1</span>, <span class="name">lookupResultFlags</span></div>
	<div class="text">A set of status flags about the result of the conversion cache lookup.</div>
      </li>
      <li>
        <div><span class="code">arg2</span>, <span class="name">hitRate</span></div>
        <div class="text">A pointer to a floating point value, between <span class="hardNobr code">0.0</span> and <span class="hardNobr code">100.0</span>, that represents the effectiveness of cache. Higher is better. Must be copied with <span class="hardNobr code">copyin(arg2, sizeof(double))</span>.</div>
      </li>
      <li>
        <div><span class="code">arg3</span>, <span class="name">string</span></div>
        <div class="text">A pointer to the <span class="code">NSString</span> that this <span class="code">UTF-16</span> conversion cache check is being performed on.</div>
      </li>
      <li>
        <div><span class="code">arg4</span>, <span class="name">NSRange_location</span></div>
        <div class="text">The location value of the <span class="argument">range</span> argument from the invoking <span class="rkl">RegexKit<i>Lite</i></span> method.</div>
      </li>
      <li>
        <div><span class="code">arg5</span>, <span class="name">NSRange_length</span></div>
        <div class="text">The length value of the <span class="argument">range</span> argument from the invoking <span class="rkl">RegexKit<i>Lite</i></span> method.</div>
      </li>
      <li>
        <div><span class="code">arg6</span>, <span class="name">length</span></div>
        <div class="text">The length of the string.</div>
      </li>
    </ul>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>Only strings that require a <span class="code">UTF-16</span> conversion count towards the value calculated for <span class="argument">hitRate</span>.</p>
    <p>An example of how to copy the <span class="code">double</span> value pointed to by <span class="argument">hitRate</span>:</p>
    <div class="box sourcecode">RegexKitLite*:::utf16ConversionCache {
  this-&gt;hitRate = (double *)copyin(arg2, sizeof(double));
  printf(&quot;utf16ConversionCache hitRate: %6.2f%%\n&quot;, this-&gt;hitRate);
}</div>

  </div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#DTrace_RegexKitLiteProbePoints__compiledRegexCache" class="code">RegexKitLite:::compiledRegexCache</a></li>
      <li><a href="#dtrace_utf16ConversionCache_lookupResultFlags" class="section-link">RegexKitLite:::utf16ConversionCache arg1 Flags</a></li>
      <li><a href="#UsingRegexKitLite_DTrace" class="section-link">Using <span class="rkl">RegexKit<i>Lite</i></span> - DTrace</a></li>
      <li><a href="http://docs.sun.com/app/docs/doc/817-6223" class="section-link printURL">Solaris Dynamic Tracing Guide</a> <a href="http://dlc.sun.com/pdf/817-6223/817-6223.pdf" class="section-link printURL">(as .PDF)</a></li>
    </ul>
  </div>
</div>



<h2>Class Methods</h2>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__.captureCountForRegex:">captureCountForRegex:</div>
  <div class="section summary">Returns the number of captures that <span class="argument">regex</span> contains. <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0.</span>  Use <a href="#NSString_RegexKitLiteAdditions__-captureCount" class="code">captureCount</a> instead.</div>
  <div class="signature"><span class="hardNobr">+ (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">captureCountForRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>Since the capture count of a regular expression does not depend on the string to be searched, this is a <span class="code">NSString</span> class method.  For example:</p>

<div class="box sourcecode">NSInteger regexCaptureCount = [NSString captureCountForRegex:@&quot;(\\d+)\.(\\d+)&quot;];
// <span class="comment">regexCaptureCount would be set to 2.</span></div>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</p></div>
  <div class="section result"><div class="header">Return Value</div>
    <p>Returns <span class="code hardNobr">-1</span> if an error occurs.  Otherwise the number of captures in <span class="argument">regex</span> is returned, or <span class="code">0</span> if <span class="argument">regex</span> does not contain any captures.</p>
  </div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__.captureCountForRegex:options:error:" class="code">+ captureCountForRegex:options:error:</a> <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</span></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureCount" class="code">- captureCount</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:" class="code">- captureCountWithOptions:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__.captureCountForRegex:options:error:">captureCountForRegex:options:error:</div>
  <div class="section summary">Returns the number of captures that <span class="argument">regex</span> contains. <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0.</span>  Use <a href="#NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:" class="code">captureCountWithOptions:error:</a> instead.</div>
  <div class="signature"><span class="hardNobr">+ (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">captureCountForRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>The optional <span class="argument">error</span> parameter, if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</p>

<p>Since the capture count of a regular expression does not depend on the string to be searched, this is a <span class="code">NSString</span> class method.  For example:</p>

<div class="box sourcecode">NSInteger regexCaptureCount = [NSString captureCountForRegex:@&quot;(\\d+)\.(\\d+)&quot; options:RKLNoOptions error:NULL];
// <span class="comment">regexCaptureCount would be set to 2.</span></div>
  </div>
  <div class="section availability"><div class="header">Availability</div>
    <p>Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</p>
  </div>
  <div class="section result"><div class="header">Return Value</div>
    <p>Returns <span class="code hardNobr">-1</span> if an error occurs.  Otherwise the number of captures in <span class="argument">regex</span> is returned, or <span class="code">0</span> if <span class="argument">regex</span> does not contain any captures.</p>
  </div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__.captureCountForRegex:" class="code">+ captureCountForRegex:</a> <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</span></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureCount" class="code">- captureCount</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:" class="code">- captureCountWithOptions:error:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__.clearStringCache">clearStringCache</div>
  <div class="section summary">Clears the cached information about strings and cached compiled regular expressions.</div>
  <div class="signature"><span class="hardNobr">+ (void)<span class="selector">clearStringCache</span>;</span></div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>This method clears all the the cached state maintained by <span class="rkl">RegexKit<i>Lite</i></span>.  This includes all the cached compiled regular expressions and any cached <span class="code">UTF-16</span> conversions.</p>

    <p>An example of clearing the cache:</p>

<div class="box sourcecode">[NSString clearStringCache]; // <span class="comment">Clears all RegexKitLite cache state.</span></div>

    <div class="box warning"><div class="table"><div class="row"><div class="label cell">Warning:</div><div class="message cell">
	<p>When searching <span class="code">NSMutableString</span> objects that have mutated between searches, failure to clear the cache may result in undefined behavior.  Use <a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="code">flushCachedRegexData</a> to selectively clear the cached information about a <span class="code">NSMutableString</span> object.</p>
    </div></div></div></div>

    <div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
	<p>You do not need to call <a href="#NSString_RegexKitLiteAdditions__.clearStringCache" class="code">clearStringCache</a> or <a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="code">flushCachedRegexData</a> when using the <span class="code">NSMutableString</span> <a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" class="code">replaceOccurrencesOfRegex:withString:</a> methods. The cache entry for that regular expression and <span class="code">NSMutableString</span> is automatically cleared as necessary.</p>
    </div></div></div></div>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.1 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="code">- flushCachedRegexData</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings" class="section-link">NSString <span class="rkl">RegexKit<i>Lite</i></span> Additions Reference - Cached Information and Mutable Strings</a></li>
    </ul>
  </div>
</div>


<h2 class="InstanceMethods">Instance Methods</h2>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:">arrayOfCaptureComponentsMatchedByRegex:</div>
  <div class="section summary">Returns an array containing all the matches from the receiver that were matched by the regular expression <span class="argument">regex</span>. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">arrayOfCaptureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSArray</span> object containing all the matches from the receiver by <span class="argument">regex</span>. Each match result consists of a <span class="code">NSArray</span> which contains all the capture groups present in <span class="argument">regex</span>.  Array index <span class="code">0</span> represents all of the text matched by <span class="argument">regex</span> and subsequent array indexes contain the text matched by their respective capture group.</p></div>
  <div class="section discussion"><div class="header">Discussion</div><p>A match result array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if a capture group did not match any text.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:" class="code">- arrayOfCaptureComponentsMatchedByRegex:range:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:" class="code">- arrayOfCaptureComponentsMatchedByRegex:options:range:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:">arrayOfCaptureComponentsMatchedByRegex:range:</div>
  <div class="section summary">Returns an array containing all the matches from the receiver that were matched by the regular expression <span class="argument">regex</span> within <span class="argument">range</span>. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">arrayOfCaptureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSArray</span> object containing all the matches from the receiver by <span class="argument">regex</span>. Each match result consists of a <span class="code">NSArray</span> which contains all the capture groups present in <span class="argument">regex</span>.  Array index <span class="code">0</span> represents all of the text matched by <span class="argument">regex</span> and subsequent array indexes contain the text matched by their respective capture group.</p></div>
  <div class="section discussion"><div class="header">Discussion</div><p>A match result array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if a capture group did not match any text.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:" class="code">- arrayOfCaptureComponentsMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:" class="code">- arrayOfCaptureComponentsMatchedByRegex:options:range:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:">arrayOfCaptureComponentsMatchedByRegex:options:range:error:</div>
  <div class="section summary">Returns an array containing all the matches from the receiver that were matched by the regular expression <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span>. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">arrayOfCaptureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSArray</span> object containing all the matches from the receiver by <span class="argument">regex</span>. Each match result consists of a <span class="code">NSArray</span> which contains all the capture groups present in <span class="argument">regex</span>.  Array index <span class="code">0</span> represents all of the text matched by <span class="argument">regex</span> and subsequent array indexes contain the text matched by their respective capture group.</p></div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSArray</span> that contains no items.</p>

<p>A match result array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if a capture group did not match any text.</p>

<p>The match results in the array appear in the order they did in the receiver. For example, this code fragment:</p>
<div class="box sourcecode">NSString *list      = <span class="hardNobr">@&quot;$10.23, $1024.42, $3099&quot;;</span>
NSArray  <span class="hardNobr">*listItems = [list</span> arrayOfCaptureComponentsMatchedByRegex:<span class="hardNobr">@&quot;\\$((\\d+)(?:\\.(\\d+)|\\.?))&quot;];</span></div>

<p style="margin-top: 0.75em">produces a <span class="code">NSArray</span> equivalent to:</p>

<div class="box sourcecode">[NSArray arrayWithObjects:
    [NSArray arrayWithObjects:  <span class="hardNobr">@&quot;$10.23&quot;,</span>   <span class="hardNobr">@&quot;10.23&quot;,</span>   <span class="hardNobr">@&quot;10&quot;,</span> <span class="hardNobr">@&quot;23&quot;,</span> <span class="hardNobr">NULL],</span> <span class="hardNobr">// <span class="comment">Index 0</span></span>
    [NSArray arrayWithObjects:<span class="hardNobr">@&quot;$1024.42&quot;,</span> <span class="hardNobr">@&quot;1024.42&quot;,</span> <span class="hardNobr">@&quot;1024&quot;,</span> <span class="hardNobr">@&quot;42&quot;,</span> <span class="hardNobr">NULL],</span> <span class="hardNobr">// <span class="comment">Index 1</span></span>
    [NSArray arrayWithObjects:   <span class="hardNobr">@&quot;$3099&quot;,</span>    <span class="hardNobr">@&quot;3099&quot;,</span> <span class="hardNobr">@&quot;3099&quot;,</span>   <span class="hardNobr">@&quot;&quot;,</span> <span class="hardNobr">NULL],</span> <span class="hardNobr">// <span class="comment">Index 2</span></span>
    NULL];</div>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:" class="code">- arrayOfCaptureComponentsMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:" class="code">- arrayOfCaptureComponentsMatchedByRegex:range:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>



<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:">arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:</div>
  <div class="section summary">Returns an array containing all the matches in the receiver that were matched by the regular expression <span class="argument">regex</span>. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">arrayOfDictionariesByMatchingRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">withKeysAndCaptures:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/id">id</a>)<span class="argument">firstKey</span>, <span class="argument">...</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">firstKey</div>
        <div class="text">The first key to add to the new dictionary.</div>
      </li>
      <li>
        <div class="name">...</div>
        <div class="text">First the <span class="argument">capture</span> for <span class="argument">firstKey</span>, then a <span class="code">NULL</span>-terminated list of alternating <span class="argument">keys</span> and <span class="argument">captures</span>.  <span class="argument">Captures</span> are specified using <span class="code">int</span> values.
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Use of non-<span class="code">int</span> sized <span class="argument">capture</span> arguments will result in undefined behavior.  <b>Do not</b> append <span class="argument">capture</span> arguments with a <span class="code">L</span> suffix.</p>
</div></div></div></div>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Failure to <span class="code">NULL</span>-terminate the <span class="argument">keys</span> and <span class="argument">captures</span> list will result in undefined behavior.</p>
</div></div></div></div></div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing all the matches from the receiver by <span class="argument">regex</span>. Each match result consists of a <span class="code">NSDictionary</span> containing that matches substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>

  <div class="section discussion"><div class="header">Discussion</div>

<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSArray</span> that contains no items.</p>

<p>A dictionary will not contain a given key if its corresponding capture group did not match any text.</p>
  </div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:" class="code">- arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:" class="code">- arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
  </ul>
</div>

</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:">arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:</div>
  <div class="section summary">Returns an array containing all the matches in the receiver that were matched by the regular expression <span class="argument">regex</span> within <span class="argument">range</span>. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">arrayOfDictionariesByMatchingRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">withKeysAndCaptures:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/id">id</a>)<span class="argument">firstKey</span>, <span class="argument">...</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">firstKey</div>
        <div class="text">The first key to add to the new dictionary.</div>
      </li>
      <li>
        <div class="name">...</div>
        <div class="text">First the <span class="argument">capture</span> for <span class="argument">firstKey</span>, then a <span class="code">NULL</span>-terminated list of alternating <span class="argument">keys</span> and <span class="argument">captures</span>.  <span class="argument">Captures</span> are specified using <span class="code">int</span> values.
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Use of non-<span class="code">int</span> sized <span class="argument">capture</span> arguments will result in undefined behavior.  <b>Do not</b> append <span class="argument">capture</span> arguments with a <span class="code">L</span> suffix.</p>
</div></div></div></div>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Failure to <span class="code">NULL</span>-terminate the <span class="argument">keys</span> and <span class="argument">captures</span> list will result in undefined behavior.</p>
</div></div></div></div></div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing all the matches from the receiver by <span class="argument">regex</span>. Each match result consists of a <span class="code">NSDictionary</span> containing that matches substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>

  <div class="section discussion"><div class="header">Discussion</div>

<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSArray</span> that contains no items.</p>

<p>A dictionary will not contain a given key if its corresponding capture group did not match any text.</p>
  </div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:" class="code">- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:" class="code">- arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
  </ul>
</div>

</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:">arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:</div>
  <div class="section summary">Returns an array containing all the matches in the receiver that were matched by the regular expression <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span>. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">arrayOfDictionariesByMatchingRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">withKeysAndCaptures:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/id">id</a>)<span class="argument">firstKey</span>, <span class="argument">...</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
      <li>
        <div class="name">firstKey</div>
        <div class="text">The first key to add to the new dictionary.</div>
      </li>
      <li>
        <div class="name">...</div>
        <div class="text">First the <span class="argument">capture</span> for <span class="argument">firstKey</span>, then a <span class="code">NULL</span>-terminated list of alternating <span class="argument">keys</span> and <span class="argument">captures</span>.  <span class="argument">Captures</span> are specified using <span class="code">int</span> values.
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Use of non-<span class="code">int</span> sized <span class="argument">capture</span> arguments will result in undefined behavior.  <b>Do not</b> append <span class="argument">capture</span> arguments with a <span class="code">L</span> suffix.</p>
</div></div></div></div>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Failure to <span class="code">NULL</span>-terminate the <span class="argument">keys</span> and <span class="argument">captures</span> list will result in undefined behavior.</p>
</div></div></div></div></div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing all the matches from the receiver by <span class="argument">regex</span>. Each match result consists of a <span class="code">NSDictionary</span> containing that matches substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>

  <div class="section discussion"><div class="header">Discussion</div>

<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSArray</span> that contains no items.</p>

<p>A dictionary will not contain a given key if its corresponding capture group did not match any text.  It is important to note that a regular expression can successfully match zero characters:</p>

<div class="box sourcecode">    NSString *name      = @&quot;Name: Bob\n&quot;
                          @&quot;Name: John Smith&quot;;
    NSString *regex     = @&quot;(?m)^Name:\\s*(\\w*)\\s*(\\w*)$&quot;;
    NSArray  *nameArray = 
    [name arrayOfDictionariesByMatchingRegex:regex
                                     options:RKLNoOptions
                                       range:NSMakeRange(0UL,)
                                       error:NULL
                         withKeysAndCaptures:@&quot;first&quot;, 1, @&quot;last&quot;, 2, NULL];

// <span class="comment">2010-04-16 01:15:30.061 RegexKitLite[42984:a0f] nameArray: (</span>
//         <span class="comment">{ first = Bob,  last = &quot;&quot;    },</span>
//         <span class="comment">{ first = John, last = Smith }</span>
// <span class="comment">)</span></div>

<p>Compared to this example, where the second capture group does not match any characters:</p>

<div class="box sourcecode">    NSString *name      = @&quot;Name: Bob\n&quot;
                          @&quot;Name: John Smith&quot;;
    NSString *regex     = @&quot;(?m)^Name:\\s*(\\w*)(?:\\s*|\\s+(\\w+))$&quot;;
    NSArray  *nameArray = 
    [name arrayOfDictionariesByMatchingRegex:regex
                                     options:RKLNoOptions
                                       range:NSMakeRange(0UL,)
                                       error:NULL
                         withKeysAndCaptures:@&quot;first&quot;, 1, @&quot;last&quot;, 2, NULL];

// <span class="comment">2010-04-16 01:15:30.061 RegexKitLite[42984:a0f] nameArray: (</span>
//         <span class="comment">{ first = Bob                },</span>
//         <span class="comment">{ first = John, last = Smith }</span>
// <span class="comment">)</span></div>
  </div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:" class="code">- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:" class="code">- arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
  </ul>
</div>

</div>



<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:">captureComponentsMatchedByRegex:</div>
  <div class="section summary">Returns an array containing the substrings matched by each capture group present in <span class="argument">regex</span> for the first match of <span class="argument">regex</span> in the receiver.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">captureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> containing the substrings matched by each capture group present in <span class="argument">regex</span> for the first match of <span class="argument">regex</span> in the receiver. Array index <span class="code">0</span> represents all of the text matched by <span class="argument">regex</span> and subsequent array indexes contain the text matched by their respective capture group.</div>
  <div class="section discussion"><div class="header">Discussion</div><p>A match result array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if a capture group did not match any text.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:" class="code">- captureComponentsMatchedByRegex:range:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:" class="code">- captureComponentsMatchedByRegex:options:range:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:">captureComponentsMatchedByRegex:range:</div>
  <div class="section summary">Returns an array containing the substrings matched by each capture group present in <span class="argument">regex</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">captureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> containing the substrings matched by each capture group present in <span class="argument">regex</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver. Array index <span class="code">0</span> represents all of the text matched by <span class="argument">regex</span> and subsequent array indexes contain the text matched by their respective capture group.</div>
  <div class="section discussion"><div class="header">Discussion</div><p>A match result array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if a capture group did not match any text.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:" class="code">- captureComponentsMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:" class="code">- captureComponentsMatchedByRegex:options:range:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:">captureComponentsMatchedByRegex:options:range:error:</div>
  <div class="section summary">Returns an array containing the substrings matched by each capture group present in <span class="argument">regex</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver using <span class="argument">options</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">captureComponentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> containing the substrings matched by each capture group present in <span class="argument">regex</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver using <span class="argument">options</span>. Array index <span class="code">0</span> represents all of the text matched by <span class="argument">regex</span> and subsequent array indexes contain the text matched by their respective capture group.</div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSArray</span> that contains no items.</p>

<p>A match result array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if a capture group did not match any text.</p>

<p>The returned value is for the first match of <span class="argument">regex</span> in the receiver.  For example, this code fragment:</p>

<div class="box sourcecode">NSString *list      = <span class="hardNobr">@&quot;$10.23, $1024.42, $3099&quot;;</span>
NSArray  <span class="hardNobr">*listItems = [list</span> captureComponentsMatchedByRegex:<span class="hardNobr">@&quot;\\$((\\d+)(?:\\.(\\d+)|\\.?))&quot;];</span></div>

<p style="margin-top: 0.75em">produces a <span class="code">NSArray</span> equivalent to:</p>

<div class="box sourcecode">[NSArray arrayWithObjects: <span class="hardNobr">@&quot;$10.23&quot;,</span> <span class="hardNobr">@&quot;10.23&quot;,</span> <span class="hardNobr">@&quot;10&quot;,</span> <span class="hardNobr">@&quot;23&quot;,</span> <span class="hardNobr">NULL];</span></div>

  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:" class="code">- captureComponentsMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:" class="code">- captureComponentsMatchedByRegex:range:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-captureCount">captureCount</div>
  <div class="section summary">Returns the number of captures that <span class="argument">regex</span> contains.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">captureCount</span>;</span></div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>Returns the capture count of the receiver, which should be a valid regular expression.  For example:</p>

<div class="box sourcecode">NSInteger regexCaptureCount = [@&quot;(\\d+)\.(\\d+)&quot; captureCount];
// <span class="comment">regexCaptureCount would be set to 2.</span></div>
  </div>
  <div class="section result"><div class="header">Return Value</div>
    <p>Returns <span class="code hardNobr">-1</span> if an error occurs.  Otherwise the number of captures in <span class="argument">regex</span> is returned, or <span class="code">0</span> if <span class="argument">regex</span> does not contain any captures.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:" class="code">- captureCountWithOptions:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:">captureCountWithOptions:error:</div>
  <div class="section summary">Returns the number of captures that <span class="argument">regex</span> contains.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">captureCountWithOptions:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>The optional <span class="argument">error</span> parameter, if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</p>

<p>Returns the capture count of the receiver, which should be a valid regular expression.  For example:</p>

<div class="box sourcecode">NSInteger regexCaptureCount = [@&quot;(\\d+)\.(\\d+)&quot; captureCountWithOptions:RKLNoOptions error:NULL];
// <span class="comment">regexCaptureCount would be set to 2.</span></div>
  </div>
  <div class="section result"><div class="header">Return Value</div>
    <p>Returns <span class="code hardNobr">-1</span> if an error occurs.  Otherwise the number of captures in <span class="argument">regex</span> is returned, or <span class="code">0</span> if <span class="argument">regex</span> does not contain any captures.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-captureCount" class="code">- captureCount</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:">componentsMatchedByRegex:</div>
  <div class="section summary">Returns an array containing all the substrings from the receiver that were matched by the regular expression <span class="argument">regex</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing all the substrings from the receiver that were matched by <span class="argument">regex</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:" class="code">- componentsMatchedByRegex:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:" class="code">- componentsMatchedByRegex:range:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:" class="code">- componentsMatchedByRegex:options:range:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:">componentsMatchedByRegex:capture:</div>
  <div class="section summary">Returns an array containing all the substrings from the receiver that were matched by capture number <span class="argument">capture</span> from the regular expression <span class="argument">regex</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing all the substrings for capture group <span class="argument">capture</span> from the receiver that were matched by <span class="argument">regex</span>.</div>
  <div class="section discussion"><div class="header">Discussion</div><p>An array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if the capture group did not match any text.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" class="code">- componentsMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:" class="code">- componentsMatchedByRegex:range:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:" class="code">- componentsMatchedByRegex:options:range:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:">componentsMatchedByRegex:range:</div>
  <div class="section summary">Returns an array containing all the substrings from the receiver that were matched by the regular expression <span class="argument">regex</span> within <span class="argument">range</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing all the substrings from the receiver that were matched by <span class="argument">regex</span> within <span class="argument">range</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" class="code">- componentsMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:" class="code">- componentsMatchedByRegex:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:" class="code">- componentsMatchedByRegex:options:range:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:">componentsMatchedByRegex:options:range:capture:error:</div>
  <div class="section summary">Returns an array containing all the substrings from the receiver that were matched by capture number <span class="argument">capture</span> from the regular expression <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">capture</div>
        <div class="text">The string matched by <span class="argument">capture</span> from <span class="argument">regex</span> to return. Use <span class="code">0</span> for the entire string that <span class="argument">regex</span> matched.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing all the substrings from the receiver that were matched by capture number <span class="argument">capture</span> from <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span>.</div>


  <div class="section discussion"><div class="header">Discussion</div>
<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSArray</span> that contains no items.</p>

<p>An array index will contain an empty string, or <span class="hardNobr code">@&quot;&quot;</span>, if a capture group did not match any text.</p>

<p>The match results in the array appear in the order they did in the receiver.</p>

<p>Example:</p>
<div class="box sourcecode">NSString *list      = <span class="hardNobr">@&quot;$10.23, $1024.42, $3099&quot;;</span>
NSArray  <span class="hardNobr">*listItems = [list</span> componentsMatchedByRegex:<span class="hardNobr">@&quot;\\$((\\d+)(?:\\.(\\d+)|\\.?))&quot;</span>];

// <span class="comment">listItems == [NSArray arrayWithObjects:@&quot;$10.23&quot;, @&quot;$1024.42&quot;, @&quot;$3099&quot;, NULL];</span></div>

<p style="margin-top: 1em">Example of extracting a specific capture group:</p>

<div class="box sourcecode">NSString *list      = <span class="hardNobr">@&quot;$10.23, $1024.42, $3099&quot;;</span>
NSRange   listRange = <span class="hardNobr">NSMakeRange(0UL,</span> <span class="hardNobr">[list length]);</span>
NSArray  <span class="hardNobr">*listItems = [list</span> componentsMatchedByRegex:<span class="hardNobr">@&quot;\\$((\\d+)(?:\\.(\\d+)|\\.?))&quot;</span> <span class="hardNobr">options:RKLNoOptions</span> <span class="hardNobr">range:listRange</span> <span class="hardNobr">capture:3L</span> <span class="hardNobr">error:NULL];</span>

// <span class="comment">listItems == [NSArray arrayWithObjects:@&quot;23&quot;, @&quot;42&quot;, @&quot;&quot;, NULL];</span></div>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" class="code">- componentsMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:" class="code">- componentsMatchedByRegex:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:" class="code">- componentsMatchedByRegex:range:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:">componentsSeparatedByRegex:</div>
  <div class="section summary">Returns an array containing substrings from the receiver that have been divided by the regular expression <span class="argument">regex</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing the substrings from the receiver that have been divided by <span class="argument">regex</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:" class="code">- componentsSeparatedByRegex:range:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:" class="code">- componentsSeparatedByRegex:options:range:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:">componentsSeparatedByRegex:range:</div>
  <div class="section summary">Returns an array containing substrings within <span class="argument">range</span> of the receiver that have been divided by the regular expression <span class="argument">regex</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing the substrings from the receiver that have been divided by <span class="argument">regex</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">- componentsSeparatedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:" class="code">- componentsSeparatedByRegex:options:range:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:">componentsSeparatedByRegex:options:range:error:</div>
  <div class="section summary">Returns an array containing substrings within <span class="argument">range</span> of the receiver that have been divided by the regular expression <span class="argument">regex</span> using <span class="argument">options</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSArray</span> object containing the substrings from the receiver that have been divided by <span class="argument">regex</span>.</div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>The substrings in the array appear in the order they did in the receiver. For example, this code fragment:</p>

<div class="box sourcecode">NSString *list      = @&quot;Norman, Stanley, Fletcher&quot;;
NSArray  *listItems = [list componentsSeparatedByRegex:@&quot;,\\s*&quot;];</div>

<p>produces an array <span class="code">{ @&quot;Norman&quot;, @&quot;Stanley&quot;, @&quot;Fletcher&quot; }</span>.</p>

<p>If the receiver begins or ends with <span class="argument">regex</span>, then the first or last substring is, respectively, empty.  For example, the <span class="hardNobr">string <span class="code">&quot;, Norman, Stanley, Fletcher&quot;</span></span> creates an array that has these <span class="hardNobr">contents: <span class="code">{ @&quot;&quot;, @&quot;Norman&quot;, @&quot;Stanley&quot;, @&quot;Fletcher&quot; }</span>.</span></p>

<p>If the receiver has no separators that are matched by <span class="argument">regex</span>&mdash;for example, <span class="code">&quot;Norman&quot;</span>&mdash;the array contains the string itself, in this <span class="hardNobr">case <span class="code">{ @&quot;Norman&quot; }</span>.</span></p>

<p>If <span class="argument">regex</span> contains capture groups&mdash;for example, <span class="code hardNobr">@&quot;,(\\s*)&quot;</span>&mdash;the array will contain the text matched by each capture group as a separate element appended to the normal result.  An additional element will be created for each capture group.  If an individual capture group does not match any text the result in the array will be a zero length string&mdash;<span class="code">@&quot;&quot;</span>. As an example&mdash;the regular expression <span class="code hardNobr">@&quot;,(\\s*)&quot;</span> would produce the <span class="hardNobr">array <span class="code">{ @&quot;Norman&quot;, @&quot; &quot;, @&quot;Stanley&quot;, @&quot; &quot;, @&quot;Fletcher&quot; }</span>.</span></p>

  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">- componentsSeparatedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:" class="code">- componentsSeparatedByRegex:range:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>



<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:">dictionaryByMatchingRegex:withKeysAndCaptures:</div>
  <div class="section summary">Creates and returns a dictionary containing the matches constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span> for the first match of <span class="argument">regex</span> in the receiver.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary_Class/Reference/Reference.html">NSDictionary</a> *)<span class="selector">dictionaryByMatchingRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">withKeysAndCaptures:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/id">id</a>)<span class="argument">firstKey</span>, <span class="argument">...</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">firstKey</div>
        <div class="text">The first key to add to the new dictionary.</div>
      </li>
      <li>
        <div class="name">...</div>
        <div class="text">First the <span class="argument">capture</span> for <span class="argument">firstKey</span>, then a <span class="code">NULL</span>-terminated list of alternating <span class="argument">keys</span> and <span class="argument">captures</span>.  <span class="argument">Captures</span> are specified using <span class="code">int</span> values.
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Use of non-<span class="code">int</span> sized <span class="argument">capture</span> arguments will result in undefined behavior.  <b>Do not</b> append <span class="argument">capture</span> arguments with a <span class="code">L</span> suffix.</p>
</div></div></div></div>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Failure to <span class="code">NULL</span>-terminate the <span class="argument">keys</span> and <span class="argument">captures</span> list will result in undefined behavior.</p>
</div></div></div></div></div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSDictionary</span> containing the matched substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>

  <div class="section discussion"><div class="header">Discussion</div>

<p>The returned value is for the first match of <span class="argument">regex</span> in the receiver.</p>

<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSDictionary</span> that contains no items.</p>

<p>A dictionary will not contain a given key if its corresponding capture group did not match any text.</p>
  </div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:" class="code">- dictionaryByMatchingRegex:range:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:" class="code">- dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
  </ul>
</div>
</div>



<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:">dictionaryByMatchingRegex:range:withKeysAndCaptures:</div>
  <div class="section summary">Creates and returns a dictionary containing the matches constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary_Class/Reference/Reference.html">NSDictionary</a> *)<span class="selector">dictionaryByMatchingRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">withKeysAndCaptures:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/id">id</a>)<span class="argument">firstKey</span>, <span class="argument">...</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">firstKey</div>
        <div class="text">The first key to add to the new dictionary.</div>
      </li>
      <li>
        <div class="name">...</div>
        <div class="text">First the <span class="argument">capture</span> for <span class="argument">firstKey</span>, then a <span class="code">NULL</span>-terminated list of alternating <span class="argument">keys</span> and <span class="argument">captures</span>.  <span class="argument">Captures</span> are specified using <span class="code">int</span> values.
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Use of non-<span class="code">int</span> sized <span class="argument">capture</span> arguments will result in undefined behavior.  <b>Do not</b> append <span class="argument">capture</span> arguments with a <span class="code">L</span> suffix.</p>
</div></div></div></div>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Failure to <span class="code">NULL</span>-terminate the <span class="argument">keys</span> and <span class="argument">captures</span> list will result in undefined behavior.</p>
</div></div></div></div></div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSDictionary</span> containing the matched substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>

  <div class="section discussion"><div class="header">Discussion</div>

<p>The returned value is for the first match of <span class="argument">regex</span> in the receiver.</p>

<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSDictionary</span> that contains no items.</p>

<p>A dictionary will not contain a given key if its corresponding capture group did not match any text.</p>
  </div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:" class="code">- dictionaryByMatchingRegex:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:" class="code">- dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
  </ul>
</div>
</div>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:">dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:</div>
  <div class="section summary">Creates and returns a dictionary containing the matches constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver using <span class="argument">options</span>.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary_Class/Reference/Reference.html">NSDictionary</a> *)<span class="selector">dictionaryByMatchingRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">withKeysAndCaptures:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/id">id</a>)<span class="argument">firstKey</span>, <span class="argument">...</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
      <li>
        <div class="name">firstKey</div>
        <div class="text">The first key to add to the new dictionary.</div>
      </li>
      <li>
        <div class="name">...</div>
        <div class="text">First the <span class="argument">capture</span> for <span class="argument">firstKey</span>, then a <span class="code">NULL</span>-terminated list of alternating <span class="argument">keys</span> and <span class="argument">captures</span>.  <span class="argument">Captures</span> are specified using <span class="code">int</span> values.
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Use of non-<span class="code">int</span> sized <span class="argument">capture</span> arguments will result in undefined behavior.  <b>Do not</b> append <span class="argument">capture</span> arguments with a <span class="code">L</span> suffix.</p>
</div></div></div></div>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
<p>Failure to <span class="code">NULL</span>-terminate the <span class="argument">keys</span> and <span class="argument">captures</span> list will result in undefined behavior.</p>
</div></div></div></div></div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div>A <span class="code">NSDictionary</span> containing the matched substrings constructed from the specified set of <span class="argument">keys</span> and <span class="argument">captures</span>.</div>

  <div class="section discussion"><div class="header">Discussion</div>

<p>The returned value is for the first match of <span class="argument">regex</span> in the receiver.</p>

<p>If the receiver is not matched by <span class="argument">regex</span> then the returned value is a <span class="code">NSDictionary</span> that contains no items.</p>

<p>A dictionary will not contain a given key if its corresponding capture group did not match any text.  It is important to note that a regular expression can successfully match zero characters:</p>

<div class="box sourcecode">NSString     *name           = @&quot;Name: Joe&quot;;
NSString     *regex          = @&quot;Name:\\s*(\\w*)\\s*(\\w*)&quot;;
NSDictionary *nameDictionary = 
                  [name dictionaryByMatchingRegex:regex
                                          options:RKLNoOptions
                                            range:NSMakeRange(0UL,)
                                            error:NULL
                              withKeysAndCaptures:@&quot;first&quot;, 1, @&quot;last&quot;, 2, NULL];

// <span class="comment">2010-01-29 12:19:54.559 RegexKitLite[64944:a0f] nameDictionary: {</span>
//     <span class="comment">first = Joe;</span>
//     <span class="comment">last = &quot;&quot;;</span>
// <span class="comment">}</span></div>

<p>Compared to this example, where the second capture group does not match any characters:</p>

<div class="box sourcecode">NSString     *name           = @&quot;Name: Joe&quot;;
NSString     *regex          = @&quot;Name:\\s*(\\w*)\\s*(\\w<span class="highlight">+)?</span>&quot;;
NSDictionary *nameDictionary =
                  [name dictionaryByMatchingRegex:regex
                                          options:RKLNoOptions
                                            range:NSMakeRange(0UL, [name length])
                                            error:NULL
                              withKeysAndCaptures:@&quot;first&quot;, 1, @&quot;last&quot;, 2, NULL];

// <span class="comment">2010-01-29 12:12:52.177 RegexKitLite[64893:a0f] nameDictionary: {</span>
//     <span class="comment">first = Joe;</span>
// <span class="comment">}</span></div>
  </div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:" class="code">- dictionaryByMatchingRegex:withKeysAndCaptures:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:" class="code">- dictionaryByMatchingRegex:range:withKeysAndCaptures:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
  </ul>
</div>
</div>



<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:">enumerateStringsMatchedByRegex:usingBlock:</div>
  <div class="section summary">Enumerates the matches in the receiver by the regular expression <span class="argument">regex</span> and executes <span class="argument">block</span> for each match found.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">enumerateStringsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span>(void (^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">YES</span> if there was no error, otherwise returns <span class="code">NO</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:" class="code">- enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:">enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:</div>
  <div class="section summary">Enumerates the matches in the receiver by the regular expression <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span> and executes <span class="argument">block</span> using <span class="argument">enumerationOptions</span> for each match found.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">enumerateStringsMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span>(void (^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html" class="code">NSError</a> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
      <li>
        <div class="name">enumerationOptions</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationNoOptions" class="code">RKLRegexEnumerationNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">YES</span> if there was no error, otherwise returns <span class="code">NO</span> and indirectly returns a <span class="code">NSError</span> object if <span class="argument">error</span> is not <span class="code">NULL</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:" class="code">- enumerateStringsMatchedByRegex:usingBlock:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    <li><a href="#RegularExpressionEnumerationOptions" class="section-link">Regular Expression Enumeration Options</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>






<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:">enumerateStringsSeparatedByRegex:usingBlock:</div>
  <div class="section summary">Enumerates the strings of the receiver that have been divided by the regular expression <span class="argument">regex</span> and executes <span class="argument">block</span> for each divided string.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">enumerateStringsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span>(void (^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">YES</span> if there was no error, otherwise returns <span class="code">NO</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:" class="code">- enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">- componentsSeparatedByRegex:</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>





<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:">enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:</div>
  <div class="section summary">Enumerates the strings of the receiver that have been divided by the regular expression <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span> and executes <span class="argument">block</span> using <span class="argument">enumerationOptions</span> for each divided string.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">enumerateStringsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span>(void (^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html" class="code">NSError</a> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
      <li>
        <div class="name">enumerationOptions</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationNoOptions" class="code">RKLRegexEnumerationNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">YES</span> if there was no error, otherwise returns <span class="code">NO</span> and indirectly returns a <span class="code">NSError</span> object if <span class="argument">error</span> is not <span class="code">NULL</span>.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:" class="code">- enumerateStringsSeparatedByRegex:usingBlock:</a></li>
    <li><a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:" class="code">- componentsSeparatedByRegex:options:range:error:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    <li><a href="#RegularExpressionEnumerationOptions" class="section-link">Regular Expression Enumeration Options</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>




<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-flushCachedRegexData">flushCachedRegexData</div>
  <div class="section summary">Clears any cached information about the receiver.</div>
  <div class="signature"><span class="hardNobr">- (void)<span class="selector">flushCachedRegexData</span>;</span></div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>This method should be used when performing searches on <span class="code">NSMutableString</span> objects and there is the possibility that the string has mutated in between calls to <span class="rkl">RegexKit<i>Lite</i></span>.</p>

    <p>This method clears the cached information for the receiver <b>only</b>.  This is more selective than <a href="#NSString_RegexKitLiteAdditions__.clearStringCache" class="code">clearStringCache</a>, which clears all the cached information from <span class="rkl">RegexKit<i>Lite</i></span>, including all the cached compiled regular expressions.</p>

    <p><span class="rkl">RegexKit<i>Lite</i></span> automatically detects the vast majority of string mutations and clears any cached information for the mutated string.  To detect mutations, <span class="rkl">RegexKit<i>Lite</i></span> records a strings <span class="code">length</span> and <span class="code">hash</span> value at the point in time when it caches data for a string.  Cached data for a string is invalidated if either of these values change between calls to <span class="rkl">RegexKit<i>Lite</i></span>.  The problem case is when a string is mutated but the strings length remains the same <b>and</b> the hash value for the mutated string is identical to the hash value of the string before it was mutated.  This is known as a <i>hash collision</i>.  Since <span class="rkl">RegexKit<i>Lite</i></span> is unable to detect that a string has mutated when this happens, the programmer needs to explicitly inform <span class="rkl">RegexKit<i>Lite</i></span> that any cached data about the receiver needs to be cleared by sending <span class="code">flushCachedRegexData</span> to the mutated string.</p>

    <p>While it is possible to have &quot;perfect mutation detection&quot;, and therefore guarantee that only valid cached data is used, it has a significant performance penalty.  The first problem is that when caching information about a string, an immutable copy of that string needs to be made.  The second problem is that determining that two strings are not identical is usually very fast and cheap&mdash; if their lengths are not the same, no further checks are required.  The most expensive case is when two strings are identical because it requires a character by character comparison of the entire string to guarantee that they are equal.  The most expensive case also happens to be the most common case, by far.  To make matters worst, Cocoa provides no public way to determine if an instance is a mutable <span class="code">NSMutableString</span> or an immutable <span class="code">NSString</span> object.  Therefore <span class="rkl">RegexKit<i>Lite</i></span> must assume the worst case that all strings are mutable and have potentially mutated between calls to <span class="rkl">RegexKit<i>Lite</i></span>.</p>

    <p><span class="rkl">RegexKit<i>Lite</i></span> is optimized for the common case which is when regular expression operations are performed on strings that are not mutating. The majority of mutations to a string can be quickly and cheaply detected by <span class="rkl">RegexKit<i>Lite</i></span> automatically. Since the programmer has the context of the string that is to be matched, and whether or not the string is being mutated, <span class="rkl">RegexKit<i>Lite</i></span> relies on the programmer to inform it whether or not the possibility exists that the string could have mutated in a way that is undetectable.</p>

    <p>An example of clearing a strings cached information:</p>

    <div class="box sourcecode">NSMutableString *mutableSearchString; // <span class="comment">Assumed to be valid.</span>
NSString *foundString = [mutableSearchString stringByMatching:@&quot;\\d+&quot;]; // <span class="comment">Searched..</span>

[mutableSearchString replaceCharactersInRange:NSMakeRange(5UL, 10UL) withString:@&quot;[replaced]&quot;]; // <span class="comment">Mutated..</span>

[mutableSearchString flushCachedRegexData]; // <span class="comment">Clear cached information about mutableSearchString.</span></div>

    <div class="box warning"><div class="table"><div class="row"><div class="label cell">Warning:</div><div class="message cell">
	    <p>Failure to clear the cached information for a <span class="code">NSMutableString</span> object that has mutated between searches may result in undefined behavior.</p>
    </div></div></div></div>
    <div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
	<p>You do not need to call <a href="#NSString_RegexKitLiteAdditions__.clearStringCache" class="code">clearStringCache</a> or <a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="code">flushCachedRegexData</a> when using the <span class="code">NSMutableString</span> <a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" class="code">replaceOccurrencesOfRegex:withString:</a> methods. The cached information for that <span class="code">NSMutableString</span> is automatically cleared as necessary.</p>
    </div></div></div></div>
  </div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__.clearStringCache" class="code">+ clearStringCache</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings" class="section-link">NSString <span class="rkl">RegexKit<i>Lite</i></span> Additions Reference - Cached Information and Mutable Strings</a></li>
    </ul>
  </div>
</div>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-isMatchedByRegex:">isMatchedByRegex:</div>
  <div class="section summary">Returns a Boolean value that indicates whether the receiver is matched by <span class="argument">regex</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">isMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:" class="code">- isMatchedByRegex:inRange:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:" class="code">- isMatchedByRegex:options:inRange:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:">isMatchedByRegex:inRange:</div>
  <div class="section summary">Returns a Boolean value that indicates whether the receiver is matched by <span class="argument">regex</span> within <span class="argument">range</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">isMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span>;</span></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:" class="code">- isMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:" class="code">- isMatchedByRegex:options:inRange:error:</a></li>
    </ul>
  </div>
</div>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:">isMatchedByRegex:options:inRange:error:</div>
  <div class="section summary">Returns a Boolean value that indicates whether the receiver is matched by <span class="argument">regex</span> within <span class="argument">range</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">isMatchedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>The optional <span class="argument">error</span> parameter, if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:" class="code">- isMatchedByRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:" class="code">- isMatchedByRegex:inRange:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-isRegexValid">isRegexValid</div>
  <div class="section summary">Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">isRegexValid</span>;</span></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-isRegexValidWithOptions:error:" class="code">- isRegexValidWithOptions:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-isRegexValidWithOptions:error:">isRegexValidWithOptions:error:</div>
  <div class="section summary">Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid using <span class="argument">options</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<span class="selector">isRegexValidWithOptions:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
<p>This method can be used to determine if a regular expression is valid.  For example:</p>
<div class="box sourcecode">NSError  *error       = NULL;
NSString *regexString = @&quot;[a-z&quot;; // <span class="comment">Missing the closing ]</span>
if([regexString isRegexValidWithOptions:RKLNoOptions error:&amp;error] == NO) {
  NSLog(@&quot;The regular expression is invalid. Error: %@&quot;, error);
}</div>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-isRegexValid" class="code">- isRegexValid</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>



<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-rangeOfRegex:">rangeOfRegex:</div>
  <div class="section summary">Returns the range for the first match of <span class="argument">regex</span> in the receiver.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="selector">rangeOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSRange</span> structure giving the location and length of the first match of <span class="argument">regex</span> in the receiver. Returns <span class="hardNobr"><span class="code">{</span><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSNotFound" class="code">NSNotFound</a><span class="code">, 0}</span></span> if the receiver is not matched by <span class="argument">regex</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:" class="code">- rangeOfRegex:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:" class="code">- rangeOfRegex:inRange:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:" class="code">- rangeOfRegex:options:inRange:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:">rangeOfRegex:capture:</div>
  <div class="section summary">Returns the range of capture number <span class="argument">capture</span> for the first match of <span class="argument">regex</span> in the receiver.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="selector">rangeOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSRange</span> structure giving the location and length of capture number <span class="argument">capture</span> for the first match of <span class="argument">regex</span> in the receiver. Returns <span class="hardNobr"><span class="code">{</span><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSNotFound" class="code">NSNotFound</a><span class="code">, 0}</span></span> if the receiver is not matched by <span class="argument">regex</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:" class="code">- rangeOfRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:" class="code">- rangeOfRegex:inRange:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:" class="code">- rangeOfRegex:options:inRange:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:">rangeOfRegex:inRange:</div>
  <div class="section summary">Returns the range for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="selector">rangeOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSRange</span> structure giving the location and length of the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver. Returns <span class="hardNobr"><span class="code">{</span><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSNotFound" class="code">NSNotFound</a><span class="code">, 0}</span></span> if the receiver is not matched by <span class="argument">regex</span> within <span class="argument">range</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:" class="code">- rangeOfRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:" class="code">- rangeOfRegex:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:" class="code">- rangeOfRegex:options:inRange:capture:error:</a></li>
    </ul>
  </div>
</div>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:">rangeOfRegex:options:inRange:capture:error:</div>
  <div class="section summary">Returns the range of capture number <span class="argument">capture</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="selector">rangeOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">capture</div>
        <div class="text">The matching range of the capture number from <span class="argument">regex</span> to return. Use <span class="code">0</span> for the entire range that <span class="argument">regex</span> matched.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSRange</span> structure giving the location and length of capture number <span class="argument">capture</span> for the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver. Returns <span class="hardNobr"><span class="code">{</span><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSNotFound" class="code">NSNotFound</a><span class="code">, 0}</span></span> if the receiver is not matched by <span class="argument">regex</span> within <span class="argument">range</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:" class="code">- rangeOfRegex:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:" class="code">- rangeOfRegex:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:" class="code">- rangeOfRegex:inRange:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>



<div class="block method">
  <div class="section name" id="NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:">replaceOccurrencesOfRegex:usingBlock:</div>
  <div class="section summary">Enumerates the matches in the receiver by the regular expression <span class="argument">regex</span> and executes <span class="argument">block</span> for each match found. Replaces the characters that were matched with the contents of the string returned by <span class="argument">block</span>, returning the number of replacements made.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *(^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>
    </ul>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.</p>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">-1</span> if there was an error, otherwise returns the number of replacements performed.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:" class="code">- replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>

<div class="block method">
  <div class="section name" id="NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:">replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:</div>
  <div class="section summary">Enumerates the matches in the receiver by the regular expression <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span> and executes <span class="argument">block</span> using <span class="argument">enumerationOptions</span> for each match found. Replaces the characters that were matched with the contents of the string returned by <span class="argument">block</span>, returning the number of replacements made.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *(^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html" class="code">NSError</a> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
      <li>
        <div class="name">enumerationOptions</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationNoOptions" class="code">RKLRegexEnumerationNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>
    </ul>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.</p>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">-1</span> if there was an error and indirectly returns a <span class="code">NSError</span> object if <span class="argument">error</span> is not <span class="code">NULL</span>, otherwise returns the number of replacements performed.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:" class="code">- replaceOccurrencesOfRegex:usingBlock:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    <li><a href="#RegularExpressionEnumerationOptions" class="section-link">Regular Expression Enumeration Options</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>




<div class="block method">
  <div class="section name" id="NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:">replaceOccurrencesOfRegex:withString:</div>
  <div class="section summary">Replaces all occurrences of the regular expression <span class="argument">regex</span> with the contents of <span class="argument">replacement</span> string after performing capture group substitutions, returning the number of replacements made.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span>;</span></div>
  <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Raises <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <span class="argument">replacement</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression <span class="argument">regex</span>.</div></div></div></div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.</p>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">-1</span> if there was an error, otherwise returns the number of replacements performed.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:" class="code">- replaceOccurrencesOfRegex:withString:range:</a></li>
      <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:" class="code">- replaceOccurrencesOfRegex:withString:options:range:error:</a></li>
      <li><a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:">replaceOccurrencesOfRegex:withString:range:</div>
  <div class="section summary">Replaces all occurrences of the regular expression <span class="argument">regex</span> within <span class="argument">range</span> with the contents of <span class="argument">replacement</span> string after performing capture group substitutions, returning the number of replacements made.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Raises <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <span class="argument">replacement</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression <span class="argument">regex</span>.</div></div></div></div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.</p>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">-1</span> if there was an error, otherwise returns the number of replacements performed.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" class="code">- replaceOccurrencesOfRegex:withString:</a></li>
      <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:" class="code">- replaceOccurrencesOfRegex:withString:options:range:error:</a></li>
      <li><a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:">replaceOccurrencesOfRegex:withString:options:range:error:</div>
  <div class="section summary">Replaces all occurrences of the regular expression <span class="argument">regex</span> using <span class="argument">options</span> within <span class="argument">range</span> with the contents of <span class="argument">replacement</span> string after performing capture group substitutions, returning the number of replacements made.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">replacement</div>
        <div class="text">The string to use as the replacement text for matches by <span class="argument">regex</span>.  See <a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a> for more information.</div>
	<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Raises <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <span class="argument">replacement</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression <span class="argument">regex</span>.</div></div></div></div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.</p>
  </div>
  <div class="section result"><div class="header">Return Value</div>Returns <span class="code">-1</span> if there was an error and indirectly returns a <span class="code">NSError</span> object if <span class="argument">error</span> is not <span class="code">NULL</span>, otherwise returns the number of replacements performed.</div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" class="code">- replaceOccurrencesOfRegex:withString:</a></li>
      <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:" class="code">- replaceOccurrencesOfRegex:withString:range:</a></li>
      <li><a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByMatching:">stringByMatching:</div>
<div class="section summary">Returns a string created from the characters of the receiver that are in the range of the first match of <span class="argument">regex</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByMatching:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSString</span> containing the substring of the receiver matched by <span class="argument">regex</span>.  Returns <span class="code">NULL</span> if the receiver is not matched by <span class="argument">regex</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:capture:" class="code">- stringByMatching:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:inRange:" class="code">- stringByMatching:inRange:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:" class="code">- stringByMatching:options:inRange:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByMatching:capture:">stringByMatching:capture:</div>
<div class="section summary">Returns a string created from the characters of the receiver that are in the range of the first match of <span class="argument">regex</span> for <span class="argument">capture</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByMatching:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSString</span> containing the substring of the receiver matched by capture number <span class="argument">capture</span> of <span class="argument">regex</span>.  Returns <span class="code">NULL</span> if the receiver is not matched by <span class="argument">regex</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:" class="code">- stringByMatching:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:inRange:" class="code">- stringByMatching:inRange:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:" class="code">- stringByMatching:options:inRange:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByMatching:inRange:">stringByMatching:inRange:</div>
<div class="section summary">Returns a string created from the characters of the receiver that are in the range of the first match of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByMatching:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSString</span> containing the substring of the receiver matched by <span class="argument">regex</span> within <span class="argument">range</span> of the receiver.  Returns <span class="code">NULL</span> if the receiver is not matched by <span class="argument">regex</span> within <span class="argument">range</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:" class="code">- stringByMatching:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:capture:" class="code">- stringByMatching:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:" class="code">- stringByMatching:options:inRange:capture:error:</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:">stringByMatching:options:inRange:capture:error:</div>
  <div class="section summary">Returns a string created from the characters of the receiver that are in the range of the first match of <span class="argument">regex</span> using <span class="argument">options</span> within <span class="argument">range</span> of the receiver for <span class="argument">capture</span>.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByMatching:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">capture:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<span class="argument">capture</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">capture</div>
        <div class="text">The string matched by <span class="argument">capture</span> from <span class="argument">regex</span> to return. Use <span class="code">0</span> for the entire string that <span class="argument">regex</span> matched.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div>
    <p>A <span class="code">NSString</span> containing the substring of the receiver matched by capture number <span class="argument">capture</span> of <span class="argument">regex</span> within <span class="argument">range</span> of the receiver.  Returns <span class="code">NULL</span> if the receiver is not matched by <span class="argument">regex</span> within <span class="argument">range</span> or an error occurs.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:" class="code">- stringByMatching:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:capture:" class="code">- stringByMatching:capture:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByMatching:inRange:" class="code">- stringByMatching:inRange:</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>



<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:">stringByReplacingOccurrencesOfRegex:usingBlock:</div>
  <div class="section summary">Enumerates the matches in the receiver by the regular expression <span class="argument">regex</span> and executes <span class="argument">block</span> for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by <span class="argument">block</span>.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">usingBlock:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *(^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>

    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSString</span> created from the characters of the receiver in which all matches of the regular expression <span class="argument">regex</span> are replaced with the contents of the <span class="code">NSString</span> returned by <span class="argument">block</span>. If the receiver is not matched by <span class="argument">regex</span> then the string that is returned is a copy of the receiver as if <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/clm/NSString/stringWithString:" class="code">stringWithString:</a> had been sent to it.</p>

<p>Returns <span class="code">NULL</span> if there was an error.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:" class="code">- stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>


<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:">stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:</div>
  <div class="section summary">Enumerates the matches in the receiver by the regular expression <span class="argument">regex</span> within <span class="argument">range</span> using <span class="argument">options</span> and executes <span class="argument">block</span> using <span class="argument">enumerationOptions</span> for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by <span class="argument">block</span>.</div>
  <div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span> <span class="selector">inRange:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span> <span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span> <span class="selector">enumerationOptions:</span>(<a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a>)<span class="argument">enumerationOptions</span> <span class="selector">usingBlock:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *(^)(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a> <span class="argument">captureCount</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <span class="argument">capturedStrings</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a> <span class="argument">capturedRanges</span>[captureCount],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;volatile <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a> * const <span class="argument">stop</span>))<span class="argument">block</span>;</div>

  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html" class="code">NSString</a> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html" class="code">NSError</a> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
      <li>
        <div class="name">enumerationOptions</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationNoOptions" class="code">RKLRegexEnumerationNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">block</div>
        <div class="text">
	  The block that is executed for each match of <span class="argument">regex</span> in the receiver.  The block takes four arguments:
	  <div class="section block parameters">
	    <ul>
	      <li>
		<div class="name">captureCount</div>
		<div class="text">The number of strings that <span class="argument">regex</span> captured.  <span class="argument">captureCount</span> is always at least <span class="code">1</span>.</div>
	      </li>
	      <li>
		<div class="name">capturedStrings</div>
		<div class="text">An array containing the substrings matched by each capture group present in <span class="argument">regex</span>. The size of the array is <span class="argument">captureCount</span>. If a capture group did not match anything, it will contain a pointer to a string that is equal to <span class="code">@&quot;&quot;</span>. This argument may be <span class="code">NULL</span> if <span class="argument">enumerationOptions</span> had <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> set.</div>
	      </li>
	      <li>
		<div class="name">capturedRanges</div>
		<div class="text">An array containing the ranges matched by each capture group present in <span class="argument">regex</span>.  The size of the array is <span class="argument">captureCount</span>.  If a capture group did not match anything, it will contain a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange" class="code">NSRange</a> equal to <span class="code">{<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/constant_group/NSNotFound">NSNotFound</a>, 0}</span>.</div>
	      </li>
	      <li>
		<div class="name">stop</div>
		<div class="text">A reference to a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL" class="code">BOOL</a> value that the block can use to stop the enumeration by setting <span class="hardNobr"><span class="code">*</span><span class="argument">stop</span><span class="code"> = <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/macro/YES">YES</a>;</span>,</span> otherwise it should not touch <span class="code">*</span><span class="argument">stop</span>.</div>
	      </li>
	    </ul>
	  </div>
	</div>
      </li>
    </ul>
  </div>

  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSString</span> created from the characters within <span class="argument">range</span> of the receiver in which all matches of the regular expression <span class="argument">regex</span> using <span class="argument">options</span> are replaced with the contents of the <span class="code">NSString</span> returned by <span class="argument">block</span>.  Returns the characters within <span class="argument">range</span> as if <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/clm/NSString/substringWithRange:" class="code">substringWithRange:</a> had been sent to the receiver if the substring is not matched by <span class="argument">regex</span>.</p>

<p>Returns <span class="code">NULL</span> if there was an error and indirectly returns a <span class="code">NSError</span> object if <span class="argument">error</span> is not <span class="code">NULL</span>.</p></div>

  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>

<div class="section seealso"><div class="header">See Also</div>
  <ul class="offset">
    <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:" class="code">- stringByReplacingOccurrencesOfRegex:usingBlock:</a></li>
    <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
    <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    <li><a href="#RegularExpressionEnumerationOptions" class="section-link">Regular Expression Enumeration Options</a></li>
    <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
    <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
  </ul>
</div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:">stringByReplacingOccurrencesOfRegex:withString:</div>
  <div class="section summary">Returns a string created from the characters of the receiver in which all matches of the regular expression <span class="argument">regex</span> are replaced with the contents of the <span class="argument">replacement</span> string after performing capture group substitutions.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span>;</span></div>
  <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Raises <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <span class="argument">replacement</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression <span class="argument">regex</span>.</div></div></div></div>
  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSString</span> created from the characters of the receiver in which all matches of the regular expression <span class="argument">regex</span> are replaced with the contents of the <span class="argument">replacement</span> string after performing capture group substitutions. If the receiver is not matched by <span class="argument">regex</span> then the string that is returned is a copy of the receiver as if <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/clm/NSString/stringWithString:" class="code">stringWithString:</a> had been sent to it.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:" class="code">- stringByReplacingOccurrencesOfRegex:withString:range:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:" class="code">- stringByReplacingOccurrencesOfRegex:withString:options:range:error:</a></li>
      <li><a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name" id="NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:">stringByReplacingOccurrencesOfRegex:withString:range:</div>
  <div class="section summary">Returns a string created from the characters within <span class="argument">range</span> of the receiver in which all matches of the regular expression <span class="argument">regex</span> are replaced with the contents of the <span class="argument">replacement</span> string after performing capture group substitutions.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span>;</span></div>
  <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Raises <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <span class="argument">replacement</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression <span class="argument">regex</span>.</div></div></div></div>
  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSString</span> created from the characters within <span class="argument">range</span> of the receiver in which all matches of the regular expression <span class="argument">regex</span> are replaced with the contents of the <span class="argument">replacement</span> string after performing capture group substitutions.  Returns the characters within <span class="argument">range</span> as if <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/clm/NSString/substringWithRange:" class="code">substringWithRange:</a> had been sent to the receiver if the substring is not matched by <span class="argument">regex</span>.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" class="code">- stringByReplacingOccurrencesOfRegex:withString:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:" class="code">- stringByReplacingOccurrencesOfRegex:withString:options:range:error:</a></li>
      <li><a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a></li>
    </ul>
  </div>
</div>

<div class="block method">
  <div class="section name softNobr" id="NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:">stringByReplacingOccurrencesOfRegex:&#8203;withString:options:range:error:</div>
  <div class="section summary">Returns a string created from the characters within <span class="argument">range</span> of the receiver in which all matches of the regular expression <span class="argument">regex</span> using <span class="argument">options</span> are replaced with the contents of the <span class="argument">replacement</span> string after performing capture group substitutions.</div>
  <div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span></span> <span class="hardNobr"><span class="selector">options:</span>(<a href="#RKLRegexOptions" class="code">RKLRegexOptions</a>)<span class="argument">options</span></span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span> <span class="hardNobr"><span class="selector">range:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSRange">NSRange</a>)<span class="argument">range</span></span> <span class="hardNobr"><span class="selector">error:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html">NSError</a> **)<span class="argument">error</span>;</span></div>
  <div class="section parameters"><div class="header">Parameters</div>
    <ul>
      <li>
        <div class="name">regex</div>
        <div class="text">A <span class="code">NSString</span> containing a regular expression.</div>
      </li>
      <li>
        <div class="name">options</div>
        <div class="text">A mask of options specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator.  Either <span class="code">0</span> or <a href="#RKLRegexOptions_RKLNoOptions" class="code">RKLNoOptions</a> may be used if no options are required.</div>
      </li>
      <li>
        <div class="name">replacement</div>
        <div class="text">The string to use as the replacement text for matches by <span class="argument">regex</span>.  See <a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a> for more information.</div>
	<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">Raises <a href="#RKLICURegexException" class="code">RKLICURegexException</a> if <span class="argument">replacement</span> contains <span class="regex">$</span><span class="argument" title="Decimal Number">n</span> capture references where <span class="argument" title="Decimal Number">n</span> is greater than the number of capture groups in the regular expression <span class="argument">regex</span>.</div></div></div></div>
      </li>
      <li>
        <div class="name">range</div>
        <div class="text">The range of the receiver to search.</div>
      </li>
      <li>
        <div class="name">error</div>
        <div class="text">An optional parameter that if set and an error occurs, will contain a <span class="code">NSError</span> object that describes the problem. This may be set to <span class="code">NULL</span> if information about any errors is not required.</div>
      </li>
    </ul>
  </div>
  <div class="section result"><div class="header">Return Value</div><p>A <span class="code">NSString</span> created from the characters within <span class="argument">range</span> of the receiver in which all matches of the regular expression <span class="argument">regex</span> using <span class="argument">options</span> are replaced with the contents of the <span class="argument">replacement</span> string after performing capture group substitutions.  Returns the characters within <span class="argument">range</span> as if <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html#//apple_ref/occ/clm/NSString/substringWithRange:" class="code">substringWithRange:</a> had been sent to the receiver if the substring is not matched by <span class="argument">regex</span>.</p></div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" class="code">- stringByReplacingOccurrencesOfRegex:withString:</a></li>
      <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:" class="code">- stringByReplacingOccurrencesOfRegex:withString:range:</a></li>
      <li><a href="#ICUSyntax_ICUReplacementTextSyntax" class="section-link">ICU Replacement Text Syntax</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
      <li><a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a></li>
    </ul>
  </div>
</div>


<h2>Constants</h2>


<div class="block typedef">
  <div class="section name" id="RKLRegexOptions">RKLRegexOptions</div>
  <div class="section summary">Type for regular expression options.</div>
  <div class="section type">typedef uint32_t RKLRegexOptions;</div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>See <a href="#RegularExpressionOptions" class="section-link">Regular Expression Options</a> for possible values.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section declared_in"><div class="header">Declared In</div>
    <div class="file">RegexKitLite.h</div>
  </div>
</div>

<div class="block typedef">
  <div class="section name" id="RegularExpressionOptions">Regular Expression Options</div>
  <div class="section summary">The following flags control various aspects of regular expression matching. The flag values may be specified at the time that a regular expression is used, or they may be specified within the pattern itself using the <span class="regex">(?ismwx-ismwx)</span> pattern options.</div>
  <div class="section declaration code table">
    <div class="top row"><div class="cell">enum {</div></div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexOptions_RKLNoOptions">RKLNoOptions</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">0,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexOptions_RKLCaseless">RKLCaseless</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">2,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexOptions_RKLComments">RKLComments</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">4,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexOptions_RKLDotAll">RKLDotAll</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">32,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexOptions_RKLMultiline">RKLMultiline</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">8,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexOptions_RKLUnicodeWordBoundaries">RKLUnicodeWordBoundaries</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">256</div>
    </div>
    <div class="bottom row"><div class="cell">};</div></div>
  </div>
  <div class="section constants"><div class="header">Constants</div>
    <div class="constant">
      <div class="identifier" id="RKLRegexOptions_RKLNoOptions">RKLNoOptions</div>
      <div class="text">No regular expression options specified.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexOptions_RKLCaseless">RKLCaseless</div>
      <div class="text">If set, matching will take place in a case-insensitive manner.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexOptions_RKLComments">RKLComments</div>
      <div class="text">If set, allow use of <span class="regex-def">white space</span> and <span class="regex">#comments</span> within patterns.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexOptions_RKLDotAll">RKLDotAll</div>
      <div class="text">If set, a <span class="regex">.</span> in a pattern will match a <span class="regex-def">line terminator</span> in the input text. By default, it will not. Note that a <span class="regex-def">carriage-return</span> / <span class="regex-def">line-feed</span> pair in text behave as a single line terminator, and will match a <span class="hardNobr">single <span class="regex">.</span> (period) in</span> a regular expression pattern.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexOptions_RKLMultiline">RKLMultiline</div>
      <div class="text">Control the behavior of <span class="regex">^</span> and <span class="regex">$</span> in a pattern. By default these will only match at the start and end, respectively, of the input text. If this flag is set, <span class="regex">^</span> and <span class="regex">$</span> will also match at the start and end of each line within the input text.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexOptions_RKLUnicodeWordBoundaries">RKLUnicodeWordBoundaries</div>
      <div class="text">Controls the behavior of <span class="regex">\b</span> in a pattern. If set, word boundaries are found according to the definitions of word found in <a href="http://www.unicode.org/reports/tr29/" class="section-link NBSP_printURL">Unicode UAX 29 - Text Boundaries</a>. By default, word boundaries are identified by means of a simple classification of characters as either <span class="regex-def">word</span> or <span class="regex-def">non-word</span>, which approximates traditional regular expression behavior. The results obtained with the two options can be quite different in runs of <span class="regex-def">spaces</span> and other <span class="regex-def">non-word</span> characters.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
    </div>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>Options for controlling the behavior of a regular expression pattern can be controlled in two ways.  When the method supports it, options may specified by combining <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flags with the C bitwise OR operator. For example:</p>

    <div class="box sourcecode"><span class="hardNobr">matchedRange = [aString</span> <span class="hardNobr">rangeOfRegex:@&quot;^(blue|red)$&quot;</span> <span class="hardNobr">options:(RKLCaseless | RKLMultiline)</span> <span class="hardNobr">inRange:range</span> <span class="hardNobr">error:NULL];</span></div>
    
    <p>The other way is to specify the options within the regular expression itself, of which there are two ways.  The first specifies the options for everything following it, and the other sets the options on a per capture group basis. Options are either <span class="hardNobr"><i>enabled</i>,</span> or following a <span class="hardNobr"><span class="regex">-</span>, <i>disabled</i>.</span> The syntax for both is nearly identical:</p>
    
    <table class="standard" summary="Option Specification in Regular Expression Patterns">
      <tr><th>Option</th><th>Example</th><th>Description</th></tr>
      <tr><td><span class="hardNobr"><span class="regex">(?</span><span class="argument">ixsmw</span><span class="regex">-</span><span class="argument">ixsmw</span><span class="regex">)</span>&hellip;</span></td><td class="hardNobr"><span class="regex">(?i)</span>&hellip;</td><td>Enables the <a href="#RKLRegexOptions_RKLCaseless" class="code">RKLCaseless</a> option for everything that follows it.  Useful at the beginning of a regular expression to set the desired options.</tr>
      <tr><td><span class="hardNobr"><span class="regex">(?</span><span class="argument">ixsmw</span><span class="regex">-</span><span class="argument">ixsmw</span><span class="regex">:</span>&hellip;<span class="regex">)</span></span></td><td><span class="regex">(?iw-m:</span>&hellip;<span class="regex">)</span></td><td>Enables the <a href="#RKLRegexOptions_RKLCaseless" class="code">RKLCaseless</a> and <a href="#RKLRegexOptions_RKLUnicodeWordBoundaries" class="code">RKLUnicodeWordBoundaries</a> options and disables <a href="#RKLRegexOptions_RKLMultiline" class="code">RKLMultiline</a> for the capture group enclosed by the parenthesis.</tr>
    </table>
    
    <p>The following table lists the regular expression pattern option character and its corresponding <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> flag:</p>
    
    <table class="standard" summary="Regular Expression Pattern Option Flags">
      <tr><th>Character</th><th>Option</th></tr>
      <tr><td><span class="regex">i</span></td><td><a href="#RKLRegexOptions_RKLCaseless" class="code">RKLCaseless</a></td></tr>
      <tr><td><span class="regex">x</span></td><td><a href="#RKLRegexOptions_RKLComments" class="code">RKLComments</a></td></tr>
      <tr><td><span class="regex">s</span></td><td><a href="#RKLRegexOptions_RKLDotAll" class="code">RKLDotAll</a></td></tr>
      <tr><td><span class="regex">m</span></td><td><a href="#RKLRegexOptions_RKLMultiline" class="code">RKLMultiline</a></td></tr>
      <tr><td><span class="regex">w</span></td><td><a href="#RKLRegexOptions_RKLUnicodeWordBoundaries" class="code">RKLUnicodeWordBoundaries</a></td></tr>
    </table>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#ICUSyntax_ICURegularExpressionSyntax" class="section-link">ICU Regular Expression Syntax</a></li>
      <li><a href="http://userguide.icu-project.org/strings/regexp" class="section-link printURL">ICU User Guide - Regular Expressions</a></li>
    </ul>
  </div>
  <div class="section declared_in"><div class="header">Declared In</div>
    <div class="file">RegexKitLite.h</div>
  </div>
</div>


<div class="block typedef">
  <div class="section name" id="RKLRegexEnumerationOptions">RKLRegexEnumerationOptions</div>
  <div class="section summary">Type for regular expression enumeration options.</div>
  <div class="section type">typedef NSUInteger RKLRegexEnumerationOptions;</div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>See <a href="#RegularExpressionEnumerationOptions" class="section-link">Regular Expression Enumeration Options</a> for possible values.</p>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell"><span class="code">RKLRegexEnumerationOptions</span> is only available if <span class="cpp_flag">RKL_BLOCKS</span> is set.</div></div></div></div>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section declared_in"><div class="header">Declared In</div>
    <div class="file">RegexKitLite.h</div>
  </div>
</div>

<div class="block typedef">
  <div class="section name" id="RegularExpressionEnumerationOptions">Regular Expression Enumeration Options</div>
  <div class="section summary">The following flags control various aspects of regular expression enumeration.</div>
  <div class="section declaration code table">
    <div class="top row"><div class="cell">enum {</div></div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationNoOptions">RKLRegexEnumerationNoOptions</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">0UL,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired">RKLRegexEnumerationCapturedStringsNotRequired</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1UL << 9,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationReleaseStringReturnedByReplacementBlock">RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1UL << 10</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX">RKLRegexEnumerationFastCapturedStringsXXX</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1UL << 11</div>
    </div>
    <div class="bottom row"><div class="cell">};</div></div>
  </div>
  <div class="section constants"><div class="header">Constants</div>
    <div class="constant">
      <div class="identifier" id="RKLRegexEnumerationOptions_RKLRegexEnumerationNoOptions">RKLRegexEnumerationNoOptions</div>
      <div class="text">No regular expression enumeration options specified.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired">RKLRegexEnumerationCapturedStringsNotRequired</div>
      <div class="text"><p>If set, this indicates that the block does not require the captured strings and <span class="code">NULL</span> will be passed to the blocks <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span> argument.</p>
<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
Methods will raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSInvalidArgumentException" class="code">NSInvalidArgumentException</a> if <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> and <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX" class="code">RKLRegexEnumerationFastCapturedStringsXXX</a> are both set.
</div></div></div></div>

</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexEnumerationOptions_RKLRegexEnumerationReleaseStringReturnedByReplacementBlock">RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</div>
      <div class="text">If set, <span class="rkl">RegexKit<i>Lite</i></span> will send the string returned by the block a <span class="code">release</span> message.  If garbage collection is active, this flag does nothing.  This flag is only valid for the <span class="hardNobr"><span class="code">stringByReplacingOccurrencesOfRegex:</span>&hellip;</span> and <span class="hardNobr"><span class="code">replaceOccurrencesOfRegex:</span>&hellip;</span> groups of methods. See <a href="#RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationReleaseStringReturnedByReplacementBlock" class="section-link">Regular Expression Enumeration Options - Using RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</a> for more information.</div>
<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
Methods will raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSInvalidArgumentException" class="code">NSInvalidArgumentException</a> if <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationReleaseStringReturnedByReplacementBlock" class="code">RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</a> is set and the block enumeration method is not a &#39;Search and Replace&#39; method.
</div></div></div></div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX">RKLRegexEnumerationFastCapturedStringsXXX</div>
      <div class="text">
<p>If set, <span class="rkl">RegexKit<i>Lite</i></span> will create the captured strings that are passed to the blocks <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span> argument in a special way.  The enumeration identifier ends in <span class="hardNobr">&hellip;<span class="code">XXX</span></span> to act as a visual reminder that special care must be taken.   See <a href="#RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationFastCapturedStringsXXX" class="section-link">Regular Expression Enumeration Options - Using RKLRegexEnumerationFastCapturedStringsXXX</a> for more information.</p>

<div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell">
Methods will raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSInvalidArgumentException" class="code">NSInvalidArgumentException</a> if <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a> and <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX" class="code">RKLRegexEnumerationFastCapturedStringsXXX</a> are both set.
</div></div></div></div>

<div class="box caution" style="margin-top: 1.25em"><div class="table"><div class="row">
<div class="label cell">Caution:</div><div class="message cell"><p><a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX" class="code">RKLRegexEnumerationFastCapturedStringsXXX</a> is an advanced feature option.  <span class="DoNot">Do not</span> use this option unless you fully understand the consequences.  Incorrect usage of this option will result in undefined behavior and will probably result in your program crashing.</p></div>
</div></div></div>

</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
    </div>
  </div>

  <div class="section discussion"><div class="header" id="RKLRegexEnumerationOptions__Discussion">Discussion</div>
    <div class="box important"><div class="table"><div class="row"><div class="label cell">Important:</div><div class="message cell"><span class="code">RKLRegexEnumerationOptions</span> is only available if <span class="cpp_flag">RKL_BLOCKS</span> is set.</div></div></div></div>
    <p>When the method supports it, enumeration options may specified by combining <a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a> flags with the C bitwise OR operator.For example:</p>
    <div class="box sourcecode">RKLRegexEnumerationOptions enumerationOptions = (RKLRegexEnumerationCapturedStringsNotRequired | RKLRegexEnumerationReleaseStringReturnedByReplacementBlock);</div>

    <p>A typical use of <span class="code">stringByReplacingOccurrencesOfRegex:</span> might be something like the following:</p>
    <div class="box sourcecode">replacedString = [aString stringByReplacingOccurrencesOfRegex:@&quot;\\w+&quot;
                                                      options:RKLNoOptions
                                                      inRange:NSMakeRange(0UL, [aString length])
                                                        error:NULL
                                           enumerationOptions:RKLRegexEnumerationNoOptions
                                                   usingBlock:^(NSInteger captureCount, NSString * const capturedStrings[captureCount], const NSRange capturedRanges[captureCount], volatile BOOL * const stop) {
  return((NSString *)[NSString stringWithFormat:@&quot;&lt;%@&gt;&quot;, capturedStrings[0]]);
}];</div>

<div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
The above example casts the value returned by <span class="code">stringWithFormat:</span>, which has a return type of <span class="code">id</span>,
to <span class="code">NSString *</span> because of a bug in <span class="consoleText">gcc</span> <span class="code">4.2.1-5646</span>.  Without the cast, the compiler gives an error that the block does not return a compatible type.  <span class="consoleText">clang</span> does not require a cast in order to compile.
</div></div></div></div>

<p>An alternate way to work around the <span class="consoleText">gcc</span> bug is to explicitly declare the return type of the block.  The example below shows how this is done with the changes highlighted:</p>

    <div class="box sourcecode"><span class="standardFont"><i>stringByReplacingOccurrencesOfRegex:&hellip;</i></span> usingBlock:^<span class="highlight">NSString *</span>(NSInteger captureCount, NSString * const capturedStrings[captureCount], const NSRange capturedRanges[captureCount], volatile BOOL * const stop) {
  return(<span class="highlight">/*(NSString *)*/</span>[NSString stringWithFormat:@&quot;&lt;%@&gt;&quot;, capturedStrings[0]]);
}];</div>

<div class="header" id="RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationReleaseStringReturnedByReplacementBlock" style="margin-top: 1em">Using <span class="code">RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</span></div>


<p>The use of convenience methods like <span class="code">stringWithFormat:</span> can create a lot of temporary strings that are autoreleased.  The memory used to hold these temporary strings won&#39;t be reclaimed until the autorelease pool that they are in is released.  When performing a replace on a large string, this can end up being a considerable about of memory.  If this is becomes a problem in your application, the <span class="code">RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</span> enumeration option can be used to reclaim the memory used by these temporary strings immediately.  <span class="code">RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</span> essentially transfers ownership of the string that is returned by the block to <span class="rkl">RegexKit<i>Lite</i></span>, which then becomes responsible for sending the string a <span class="code">release</span> message when it is no longer needed.  Typically this is right after <span class="rkl">RegexKit<i>Lite</i></span> has appended the contents of the returned string to the temporary internal string of all the accumulated replacement strings returned by the block.  For example:</p>

    <div class="box sourcecode">replacedString = [aString stringByReplacingOccurrencesOfRegex:@&quot;\\w+&quot;
                                                      options:RKLNoOptions
                                                      inRange:NSMakeRange(0UL, [aString length])
                                                        error:NULL
                                           enumerationOptions:RKLRegexEnumerationReleaseStringReturnedByReplacementBlock
                                                   usingBlock:^NSString *(NSInteger captureCount, NSString * const capturedStrings[captureCount], const NSRange capturedRanges[captureCount], volatile BOOL * const stop) {
  return([[NSString alloc] initWithFormat:@&quot;&lt;%@&gt;&quot;, capturedStrings[0]]);
}];</div>

<p>When using <span class="code">RKLRegexEnumerationReleaseStringReturnedByReplacementBlock</span>, it is also possible to directly return the strings that were passed via <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span>.  <span class="rkl">RegexKit<i>Lite</i></span> automatically checks if the pointer of the string returned by the block is equal to the pointer of any of the strings it created and passed via <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span>, in which case <span class="rkl">RegexKit<i>Lite</i></span> does not send the string that was returned a <span class="code">release</span> message since this would result in over releasing the string object.  For example:</p>

    <div class="box sourcecode">replacedString = [aString stringByReplacingOccurrencesOfRegex:@&quot;\\w+&quot;
                                                      options:RKLNoOptions
                                                      inRange:NSMakeRange(0UL, [aString length])
                                                        error:NULL
                                           enumerationOptions:RKLRegexEnumerationReleaseStringReturnedByReplacementBlock
                                                   usingBlock:^NSString *(NSInteger captureCount, NSString * const capturedStrings[captureCount], const NSRange capturedRanges[captureCount], volatile BOOL * const stop) {
  if([capturedStrings[0] isEqual:@&quot;with&quot;]) { return(capturedStrings[0]); }
  else { return([[NSString alloc] initWithFormat:@&quot;&lt;%@&gt;&quot;, capturedStrings[0]]); }
}];</div>


<div class="header" id="RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationFastCapturedStringsXXX" style="margin-top: 1em">Using <span class="code">RKLRegexEnumerationFastCapturedStringsXXX</span></div>

<p>Normally, <span class="rkl">RegexKit<i>Lite</i></span> instantiates a new string object for each string passed via <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span>. When <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX" class="code">RKLRegexEnumerationFastCapturedStringsXXX</a> is set, <span class="rkl">RegexKit<i>Lite</i></span> creates up to <span class="argument">captureCount</span> strings using the <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> function <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CFMutableStringRef/Reference/reference.html#//apple_ref/c/func/CFStringCreateMutableWithExternalCharactersNoCopy" class="code">CFStringCreateMutableWithExternalCharactersNoCopy</a> and passes these strings via <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span>.</p>

<div class="box caution"><div class="table"><div class="row">
<div class="label cell">Caution:</div><div class="message cell"><p><a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX" class="code">RKLRegexEnumerationFastCapturedStringsXXX</a> is an advanced feature option.  <span class="DoNot">Do not</span> use this option unless you fully understand the consequences.  Incorrect usage of this option will result in undefined behavior and will probably result in your program crashing.</p></div>
</div></div></div>

<p>The reason for doing this is strings created with <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CFMutableStringRef/Reference/reference.html#//apple_ref/c/func/CFStringCreateMutableWithExternalCharactersNoCopy" class="code">CFStringCreateMutableWithExternalCharactersNoCopy</a> can have the strings buffer set directly with <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CFMutableStringRef/Reference/reference.html#//apple_ref/c/func/CFStringSetExternalCharactersNoCopy" class="code">CFStringSetExternalCharactersNoCopy</a>. This allows <span class="rkl">RegexKit<i>Lite</i></span> to quickly update the strings that were captured by a match and is <b><i>much</i></b> faster than instantiating new strings for each match iteration since the only thing that needs to be updated is the captured strings pointer and length. In fact, the speed of <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX" class="code">RKLRegexEnumerationFastCapturedStringsXXX</a> is nearly has fast as <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationCapturedStringsNotRequired" class="code">RKLRegexEnumerationCapturedStringsNotRequired</a>.</p>

<p>Special care must be taken when using the strings passed via <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span> when <a href="#RKLRegexEnumerationOptions_RKLRegexEnumerationFastCapturedStringsXXX" class="code">RKLRegexEnumerationFastCapturedStringsXXX</a> has been set.  The following rules must be followed:</p>

<ul class="square">
  <li>The lifetime of the string is the duration of the blocks execution.  The string <b><i>can not</i></b> be used or referenced past the closing brace of the block.</li>
  <li><b><i><u>Do not</u></i></b> mutate any of <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span>.</li>
  <li><b><i><u>Do not</u></i></b> <span class="code">retain</span> or <span class="code">release</span> any of the <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span>.</li>
  <li><p>If you need the string to exist past the end of the block, a <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSObject_Class/Reference/Reference.html#//apple_ref/occ/instm/NSObject/copy" class="code">-copy</a> of the string must be made:</p>
<div class="box sourcecode">NSString *copiedString = [[capturedStrings[0] copy] autorelease];</div>
  </li>
</ul>

<p>Example usages:</p>

<ul class="square">
  <li><p>When using <span class="hardNobr"><span class="argument">capturedStrings</span><span class="code">[]</span></span> as an argument to <span class="code">stringWithFormat:</span>, you do not need to make a copy of the captured string:</p>
<div class="box sourcecode">[searchString <span class="hardNobr">stringByReplacingOccurrencesOfRegex:regex</span> <span class="hardNobr">usingBlock:^NSString *(NSInteger captureCount,</span> <span class="hardNobr">NSString * const capturedStrings[captureCount],</span> <span class="hardNobr">const NSRange capturedRanges[captureCount],</span> <span class="hardNobr">volatile BOOL * const stop) {</span>
  NSString *replacedString = NULL;
  replacedString = [NSString <span class="hardNobr">stringWithFormat:@&quot;{1: &#39;%@&#39;}&quot;,</span> <span class="hardNobr">capturedStrings[1]];</span> // <span class="comment">OK to use directly.</span>
  return(replacedString);
}];</div>

  <li><p>Adding to a collection:</p>
    <div class="box sourcecode">[aDictionary <span class="hardNobr">setObject:capturedStrings[0]</span> <span class="hardNobr">forKey:@&quot;aKey&quot;];</span>                      // <span class="comment"><b><u>Do not</u></b> add a captured string directly to a collection.</span>
[aDictionary setObject:<span class="hardNobr">[[capturedStrings[0] copy] autorelease]</span> <span class="hardNobr">forKey:@&quot;aKey&quot;];</span> // <span class="comment"><b><u>Do</u></b> add a copy of the captured string to a collection.</span></div>
  </li>
  <li><p>Assigning a captured string to a variable whose scope extends past the blocks:</p>
    <div class="box sourcecode">__block NSString *foundString = NULL;

[searchString <span class="hardNobr">enumerateStringsMatchedByRegex:regex</span> <span class="hardNobr">usingBlock:^(NSInteger captureCount,</span> <span class="hardNobr">NSString * const capturedStrings[captureCount],</span> <span class="hardNobr">const NSRange capturedRanges[captureCount],</span> <span class="hardNobr">volatile BOOL * const stop) {</span>
  <span class="hardNobr">foundString = capturedStrings[0];</span>                      // <span class="comment"><b><u>Do not</u></b> assign a captured string to a variable whose scope extends past the blocks.</span>
  foundString = <span class="hardNobr">[[capturedStrings[0] copy] autorelease];</span> // <span class="comment"><b><u>Do</u></b> assign a copy of the captured string to a variable whose scope extends past the blocks.</span>
}];</div>
</li>
</ul>

  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> <span class="code"><i>NSString</i></span> Additions Reference - Block-based Enumeration Methods</a></li>
      <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html" class="section-link">Blocks Programming Topics</a></li>
    </ul>
  </div>
  <div class="section declared_in"><div class="header">Declared In</div>
    <div class="file">RegexKitLite.h</div>
  </div>
</div>



<div class="block typedef">
  <div class="section name" id="dtrace_utf16ConversionCache_lookupResultFlags">RegexKitLite:::utf16ConversionCache <span class="argument">arg1</span> Flags</div>
  <div class="section summary">The following flags are used to indicate the status of the result from <span class="argument">arg1</span> <span class="argument">lookupResultFlags</span> of the <span class="code">RegexKitLite:::utf16ConversionCache</span> DTrace probe point.</div>
  <div class="section declaration code table">
    <div class="top row"><div class="cell">enum {</div></div>
    <div class="enum row">
      <div class="identifier cell"><a href="#dtrace_utf16ConversionCache_lookupResultFlags_RKLCacheHitLookupFlag">RKLCacheHitLookupFlag</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1 &lt;&lt; 0,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#dtrace_utf16ConversionCache_lookupResultFlags_RKLConversionRequiredLookupFlag">RKLConversionRequiredLookupFlag</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1 &lt;&lt; 1,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#dtrace_utf16ConversionCache_lookupResultFlags_RKLSetTextLookupFlag">RKLSetTextLookupFlag</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1 &lt;&lt; 2,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#dtrace_utf16ConversionCache_lookupResultFlags_RKLDynamicBufferLookupFlag">RKLDynamicBufferLookupFlag</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1 &lt;&lt; 3,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#dtrace_utf16ConversionCache_lookupResultFlags_RKLErrorLookupFlag">RKLErrorLookupFlag</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1 &lt;&lt; 4,</div>
    </div>
    <div class="enum row">
      <div class="identifier cell"><a href="#dtrace_utf16ConversionCache_lookupResultFlags_RKLEnumerationBufferLookupFlag">RKLEnumerationBufferLookupFlag</a></div>
      <div class="equals cell">=</div>
      <div class="constant cell">1 &lt;&lt; 5</div>
    </div>
    <div class="bottom row"><div class="cell">};</div></div>
  </div>
  <div class="section constants"><div class="header">Constants</div>
    <div class="constant">
      <div class="identifier" id="dtrace_utf16ConversionCache_lookupResultFlags_RKLCacheHitLookupFlag">RKLCacheHitLookupFlag</div>
      <div class="text">If set, there was a successful lookup hit.  This flag is only set if <span class="code">RKLConversionRequiredLookupFlag</span> is also set.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="dtrace_utf16ConversionCache_lookupResultFlags_RKLConversionRequiredLookupFlag">RKLConversionRequiredLookupFlag</div>
      <div class="text">If set, direct access to a strings <span class="code">UTF-16</span> buffer was not available and a conversion was required.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="dtrace_utf16ConversionCache_lookupResultFlags_RKLSetTextLookupFlag">RKLSetTextLookupFlag</div>
      <div class="text">If set, the ICU <span class="code">uregex_setText()</span> function was called in order to set the compiled regular expression to a buffer.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="dtrace_utf16ConversionCache_lookupResultFlags_RKLDynamicBufferLookupFlag">RKLDynamicBufferLookupFlag</div>
      <div class="text">If set, the strings size was large enough to require the use of the dynamically sized conversion buffer.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="dtrace_utf16ConversionCache_lookupResultFlags_RKLErrorLookupFlag">RKLErrorLookupFlag</div>
      <div class="text">If set, there was some kind of error during the <span class="code">UTF-16</span> conversion process.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 3.0 and later.</div>
    </div>
    <div class="constant">
      <div class="identifier" id="dtrace_utf16ConversionCache_lookupResultFlags_RKLEnumerationBufferLookupFlag">RKLEnumerationBufferLookupFlag</div>
      <div class="text">If set, the probe was fired due to a blocks enumeration.  The conversion result is one time use only and is only available to the block enumeration that required it.</div>
      <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
    </div>
  </div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="#DTrace_RegexKitLiteProbePoints__utf16ConversionCache" class="code">RegexKitLite:::utf16ConversionCache</a></li>
    </ul>
  </div>
</div>


<h3 id="RegexKitLiteNSErrorErrorDomains"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</h3>

<div class="block constants">
  <div class="section summary">The following <span class="code">NSError</span> error domains are defined.</div>
  <div class="section declaration table">
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexErrorDomain">RKLICURegexErrorDomain</a>;</div></div>
  </div>
  <div class="section constants"><div class="header">Constants</div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexErrorDomain">RKLICURegexErrorDomain</div>
    <div class="text">ICU Regular Expression Errors.</div>
  </div>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html" class="section-link printURL_small">NSError Class Reference</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    </ul>
  </div>
  <div class="section declared_in"><div class="header">Declared In</div>
    <div class="file">RegexKitLite.h</div>
  </div>
</div>

<h3 id="RegexKitLiteNSExceptionExceptionNames"><span class="rkl">RegexKit<i>Lite</i></span> NSException Exception Names</h3>

<div class="block constants">
  <div class="section summary">The following <span class="code">NSException</span> exception names are defined.</div>
  <div class="section declaration table">
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexException">RKLICURegexException</a>;</div></div>
  </div>
  <div class="section constants"><div class="header">Constants</div>
    <div class="section constant">
      <div class="identifier" id="RKLICURegexException">RKLICURegexException</div>
      <div class="text">ICU Regular Expression Exceptions</div>
    </div>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>Returns a user info dictionary populated with keys as defined in <a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a>.</p>
  </div>
  <div class="section availability"><div class="header">Availability</div><p>Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</p></div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSException_Class/Reference/Reference.html" class="section-link printURL_small">NSException Class Reference</a></li>
      <li><a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a></li>
    </ul>
  </div>
  <div class="section declared_in"><div class="header">Declared In</div>
    <div class="file">RegexKitLite.h</div>
  </div>
</div>


<h3 id="RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</h3>

<div class="block constants">
  <div class="section declaration table">
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexEnumerationOptionsErrorKey">RKLICURegexEnumerationOptionsErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexErrorCodeErrorKey">RKLICURegexErrorCodeErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexErrorNameErrorKey">RKLICURegexErrorNameErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexLineErrorKey">RKLICURegexLineErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexOffsetErrorKey">RKLICURegexOffsetErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexPreContextErrorKey">RKLICURegexPreContextErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexPostContextErrorKey">RKLICURegexPostContextErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexRegexErrorKey">RKLICURegexRegexErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexRegexOptionsErrorKey">RKLICURegexRegexOptionsErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexReplacedCountErrorKey">RKLICURegexReplacedCountErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexReplacedStringErrorKey">RKLICURegexReplacedStringErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexReplacementStringErrorKey">RKLICURegexReplacementStringErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexSubjectRangeErrorKey">RKLICURegexSubjectRangeErrorKey</a>;</div></div>
    <div class="row"><div class="name cell">extern <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> * const <a href="#RKLICURegexSubjectStringErrorKey">RKLICURegexSubjectStringErrorKey</a>;</div></div>
  </div>
  <div class="section constants"><div class="header">Constants</div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexEnumerationOptionsErrorKey">RKLICURegexEnumerationOptionsErrorKey</div>
    <div class="text">The <a href="#RKLRegexEnumerationOptions" class="code">RKLRegexEnumerationOptions</a> enumeration options specified.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexErrorCodeErrorKey">RKLICURegexErrorCodeErrorKey</div>
    <div class="text">The error code returned by the ICU library function calls <span class="argument">status</span> argument.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 2.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexErrorNameErrorKey">RKLICURegexErrorNameErrorKey</div>
    <div class="text">The string returned by invoking <a href="http://www.icu-project.org/apiref/icu4c/utypes_8h.html#89eb455526bb29bf5350ee861d81df92" class="code">u_errorName</a> with the error code <a href="#RKLICURegexErrorCodeErrorKey" class="code">RKLICURegexErrorCodeErrorKey</a>.  Example: <span class="quotedText">U_REGEX_RULE_SYNTAX</span>.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexLineErrorKey">RKLICURegexLineErrorKey</div>
    <div class="text">The line number where the error occurred in the regular expression.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexOffsetErrorKey">RKLICURegexOffsetErrorKey</div>
    <div class="text">The offset from the beginning of the line where the error occurred in the regular expression.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexPreContextErrorKey">RKLICURegexPreContextErrorKey</div>
    <div class="text">Up to <span class="code">16</span> characters leading up to the cause error in the regular expression.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexPostContextErrorKey">RKLICURegexPostContextErrorKey</div>
    <div class="text">Up to <span class="code">16</span> characters after the cause error in the regular expression.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexRegexErrorKey">RKLICURegexRegexErrorKey</div>
    <div class="text">The regular expression that caused the error.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexRegexOptionsErrorKey">RKLICURegexRegexOptionsErrorKey</div>
    <div class="text">The <a href="#RKLRegexOptions" class="code">RKLRegexOptions</a> regular expression options specified.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 1.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexReplacedCountErrorKey">RKLICURegexReplacedCountErrorKey</div>
    <div class="text">The number of times a replacement was performed.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexReplacedStringErrorKey">RKLICURegexReplacedStringErrorKey</div>
    <div class="text">The replaced string result after performing the search and replace operations.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexReplacementStringErrorKey">RKLICURegexReplacementStringErrorKey</div>
    <div class="text">The replacement template string used to perform search and replace operations.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexSubjectRangeErrorKey">RKLICURegexSubjectRangeErrorKey</div>
    <div class="text">The range of the subject string that was being matched by the regular expression.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
  </div>
  <div class="section constant">
    <div class="identifier" id="RKLICURegexSubjectStringErrorKey">RKLICURegexSubjectStringErrorKey</div>
    <div class="text">The string that was being matched by the regular expression.</div>
    <div class="text">Available in <span class="rkl">RegexKit<i>Lite</i></span> 4.0 and later.</div>
  </div>
  </div>
  <div class="section discussion"><div class="header">Discussion</div>
    <p>Different error keys will be present depending on the type of error encountered.</p>
  </div>
  <div class="section seealso"><div class="header">See Also</div>
    <ul>
      <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/Reference/Reference.html" class="section-link printURL_small">NSError Class Reference</a></li>
      <li><a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSException_Class/Reference/Reference.html" class="section-link printURL_small">NSException Class Reference</a></li>
      <li><a href="#RegexKitLiteNSErrorErrorDomains" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError Error Domains</a></li>
      <li><a href="#RegexKitLiteNSExceptionExceptionNames" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSException Exception Names</a></li>
    </ul>
  </div>
  <div class="section declared_in"><div class="header">Declared In</div>
    <div class="file">RegexKitLite.h</div>
  </div>
</div>

</div>

<div class="printPageBreakAfter">
  <h2 id="ReleaseInformation">Release Information</h2>
  
  <div class="chrono">

    <div class="entry">
      <div class="banner"><span class="date">2008/03/23</span><span class="bannerItemSpacer">-</span><span class="release">1.0</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	<p>Initial release.</p>
      </div>
    </div>
    
    <div class="entry">
      <div class="banner"><span class="date">2008/03/28</span><span class="bannerItemSpacer">-</span><span class="release">1.1</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>Changes:</p>
	<ul class="square">
          <li>Added the method <a href="#NSString_RegexKitLiteAdditions__.clearStringCache" title="Clears the cached information about strings." class="code">clearStringCache</a>.</li>
	  <li>Updated the documentation with information about searching <span class="code">NSMutableString</span> strings, and when to use <a href="#NSString_RegexKitLiteAdditions__.clearStringCache" title="Clears the cached information about strings." class="code">clearStringCache</a>.</li>
	</ul>
	
	<p>Bug fixes:</p>
	<ul class="square">
          <li>Fixed a bug that for strings that required <span class="code hardNobr">UTF-16</span> conversion, the conversion from the previous string that required conversion may have been re-used for the current string, even though the two strings are different and the new string requires conversion.</li>
	  <li>Updated the internal inconsistency exception macro to correctly handle <span class="hardNobr">non-<span class="code">ASCII</span></span> file names.</li>
	</ul>
      </div>
    </div>

    <div class="entry">
      <div class="banner"><span class="date">2008/04/01</span><span class="bannerItemSpacer">-</span><span class="release">1.2</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>Changes:</p>
	<ul class="square">
	  <li>Updated and clarified the documentation regarding adding <span class="rkl">RegexKit<i>Lite</i></span> to an Xcode project.</li>
	  <li>Created Xcode 3 DocSet documentation.</li>
	</ul>
      </div>
    </div>

    
    <div class="entry">
      <div class="banner"><span class="date">2008/07/07</span><span class="bannerItemSpacer">-</span><span class="release">2.0</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	<p>New features:</p>
	<ul class="square">
	  <li>The ability to split a string in to a <span class="code">NSArray</span> with a regular expression.</li>
	  <li>Search and replace using common <span class="hardNobr"><span class="regex">$</span><span class="argument">n</span></span> capture substitution in the replacement string.</li>
	  <li>Support for Leopards Garbage Collection</li>
	</ul>

	<p>Changes:</p>
	<ul class="square">
	  <li>A new compile time configuration option, <span class="cpp_flag">RKL_FAST_MUTABLE_CHECK</span>, enables the use of a private, non-public <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> function to determine if the string that will be searched is immutable.  This allows many of the mutation safety checks to be skipped for that string and can significantly improve the performance of repeated matches on the same immutable <span class="code">NSString</span>.  For safety, this option is disabled by default.</li>
	  <li>Gives a warning at compile time if the minimum <span class="hardNobr">Mac OS X</span> target <span class="hardNobr">is &lt; 10.3,</span> which is the first version that shipped with the ICU library.</li>
	  <li>Compile time tunable setting of how much of the stack can be used before switching to heap based storage.  Changed by setting <span class="cpp_flag">RKL_STACK_LIMIT</span> to the maximum number of bytes to use from the stack.  Defaults to <span class="code">131072</span>, or <span class="code">128Kbytes</span>.  By default in Cocoa the main thread has a stack size of <span class="code">8Mbytes</span> and additional threads have a stack size of <span class="code">512Kbytes</span>.</li>
	  <li>New <span class="code">NSException</span> name for <span class="rkl">RegexKit<i>Lite</i></span> specific exceptions, <a href="#RKLICURegexException" class="code">RKLICURegexException</a>.</li>
	  <li>Garbage Collection is safe to use in <span class="hardNobr">"mixed-mode"</span> Garbage Collection applications.  When compiled with Garbage Collection <span class="hardNobr">support (<span class="code">-fobjc-gc</span>),</span> <span class="rkl">RegexKit<i>Lite</i></span> will dynamically select either Garbage Collection or manual memory management at run-time depending on whether or not Garbage Collection is enabled and active.</li> 
	</ul>

	<p>New <span class="code">NSString</span> Methods:</p>
	<ul class="square">
	  <li><div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<span class="selector">componentsSeparatedByRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</div></li>
	  <li><div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="selector">stringByReplacingOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span>;</div></li>
	</ul>

	<p>New <span class="code">NSMutableString</span> Methods:</p>
	<ul class="square">
	  <li><div class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSUInteger">NSUInteger</a>)<span class="selector">replaceOccurrencesOfRegex:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span> <span class="hardNobr"><span class="selector">withString:</span>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">replacement</span></span>;</div></li>
	</ul>

      </div>
    </div>

    <div class="entry">
      <div class="banner"><span class="date">2008/07/12</span><span class="bannerItemSpacer">-</span><span class="release">2.1</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>Bug fixes:</p>
	<ul class="square">
	  <li>Fixed a bug dealing with the <span class="code">UTF-16</span> conversion cache.  A bug could cause the text in the conversion buffer to be incorrectly used for the wrong string.</li>
	</ul>
      </div>
    </div>

    <div class="entry">
      <div class="banner"><span class="date">2008/10/19</span><span class="bannerItemSpacer">-</span><span class="release">2.2</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>This release contains several large documentation additions and a few bug fixes.  No new major functionality was added.</p>

	<p>Documentation Changes:</p>
	<ul class="square">
	  <li>Added a section covering <a href="#ICUSyntax_ICURegularExpressionCharacterClasses">ICU Regular Expression Character Classes</a></li>
	  <li>Added a section covering <a href="#ICUSyntax_UnicodeProperties">Unicode Properties</a>, which are specified in a regular expression with <span class="hardNobr"><span class="regex">\p{</span><i>Unicode Property Name</i><span class="regex">}</span></span> and <span class="hardNobr"><span class="regex">\P{</span><i>Unicode Property Name</i><span class="regex">}</span></span>.</li>
	  <li>Added the <a href="#RegexKitLiteCookbook"><span class="rkl">RegexKit<i>Lite</i></span> Cookbook</a> section.  Special <i>Copy to Clipboard</i> functionality is enabled for Safari users that allows a regular expression in this document that is selected and <i>Copied to the Clipboard</i> to be automatically escaped so the regular expression can be pasted directly in to your source code, ready to be used, with no additional work required.</li>
	  <li>Added the <a href="#Epilogue">Epilogue</a> section.  This section is meant to be less formal, where I can place bits and pieces that don&#39;t fit elsewhere or editorialize on some topic.</li>
	  <li>A number of small additions, deletions, and edits through out the documentation.</li>
	</ul>

	<p>Changes:</p>
	<ul class="square">
	  <li>A new compile time configuration option, <span class="cpp_flag">RKL_METHOD_PREPEND</span>, can be used to add custom prefix to all the <span class="rkl">RegexKit<i>Lite</i></span> methods.  For example, setting <span class="cpp_flag">RKL_METHOD_PREPEND</span> to <span class="code">xyz_</span> would cause <span class="code">stringByReplacingOccurrencesOfRegex:withString:</span> to become <span class="code">xyz_stringByReplacingOccurrencesOfRegex:withString:</span>.  This is for users who prefer that any category additions to the core classes, such as <span class="code">NSString</span>, have a user defined prefix to prevent the possibility of user defined method names interfering with later system defined method names.</li>

	  <li>Support for iPhone low memory notifications.  When it can be determined at compile time that the iPhone is being targeted, the preprocessor flag <span class="cpp_flag">RKL_REGISTER_FOR_IPHONE_LOWMEM_NOTIFICATIONS</span> is enabled to add code that automatically registers for low memory notifications on the iPhone.  When a low memory notification is received, <span class="rkl">RegexKit<i>Lite</i></span> will flush all its caches, freeing the memory used to hold the cached data.</li>
	</ul>

	<p>Bug fixes:</p>
	<ul class="square">
	  <li>
	    <p><a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2105213&amp;group_id=%20204582&amp;atid=990188" class="printURL">Bug 2105213</a></p>

	    <p>Fixed a bug in <a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" class="code">stringByReplacingOccurrencesOfRegex:withString:</a> and <a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" class="code">replaceOccurrencesOfRegex:withString:</a> where if the receiver was an empty string (i.e., <span class="code">@&quot;&quot;</span>), then <span class="rkl">RegexKit<i>Lite</i></span> would throw an exception because the ICU library reported an error.  This turned out to be a bug in the ICU library itself in the <span class="code">uregex_reset()</span> function (and the methods it calls to perform its work).  A bug was opened with the ICU project: <a href="http://bugs.icu-project.org/trac/ticket/6545">http://bugs.icu-project.org/trac/ticket/6545</a>.  A work-around for the buggy behavior was put in place so that if the ICU library reports a <span class="code">U_INDEX_OUTOFBOUNDS_ERROR</span> error for a string with a length of zero, that error is ignored since it is spurious.  Thanks go to Andy Kim for reporting this.</p>
	  </li>
	  <li>
	    <p><a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2050825&amp;group_id=%20204582&amp;atid=990188" class="printURL">Bug 2050825</a></p>

	    <p>Fixed a bug with <span class="code">NSScannedOption</span> when targeting the iPhone.  <span class="code">NSScannedOption</span> is not available on the iPhone, so C Pre-Processor statements were added to ensure that <span class="code">NSScannedOption</span> is not referenced when Objective-C Garbage Collection is not enabled.  Thanks go to Shaun Inman for reporting this first.</p>
	  </li>

	  <li>Fixed a bug in <a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:" class="code">stringByReplacingOccurrencesOfRegex:withString:</a> and <a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:" class="code">replaceOccurrencesOfRegex:withString:</a> where an internal assertion exception would be thrown if the string to search and the replacement string were both zero length strings (i.e., <span class="code">@&quot;&quot;</span>).</li>
	</ul>
      </div>
    </div>

    <div class="entry" id="ReleaseInformation_30">
      <div class="banner"><span class="date">2009/05/06</span><span class="bannerItemSpacer">-</span><span class="release">3.0</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>This release of <span class="rkl">RegexKit<i>Lite</i></span> is a major release that includes new features, new APIs, and a number of bug fixes.</p>

	<p>New Features:</p>
	<ul class="square">
	  <li>DTrace support. This release includes <span class="rkl">RegexKit<i>Lite</i></span> specific DTrace provider probe points that allow you to monitor the effectiveness of <span class="rkl">RegexKit<i>Lite</i></span>&#39;s caches.  DTrace support can be enabled with the compile time configuration option <span class="cpp_flag">RKL_DTRACE</span>.</li>
	  <li>Easy support for custom built ICU libraries. A new compile time configuration option, <span class="cpp_flag">RKL_APPEND_TO_ICU_FUNCTIONS</span>, can be used to append a string to the ICU functions called by <span class="rkl">RegexKit<i>Lite</i></span>.  Custom builds of the ICU library include the ICU version appended to all functions by default and this feature allows you to easily retarget <span class="rkl">RegexKit<i>Lite</i></span> to your custom build. Example usage: <span class="consoleText">-DRKL_APPEND_TO_ICU_FUNCTIONS=_4_0</span></li>
	</ul>

	<p>New <span class="code">NSString</span> Methods:</p>
	<ul class="square">
	  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<a href="#NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:" class="selector">arrayOfCaptureComponentsMatchedByRegex:</a>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div></li>
	  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<a href="#NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:" class="selector">captureComponentsMatchedByRegex:</a>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div></li>
	  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<a href="#NSString_RegexKitLiteAdditions__-captureCount" class="selector">captureCount</a>;</span></div></li>
	  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html">NSArray</a> *)<a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" class="selector">componentsMatchedByRegex:</a>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></div></li>
	  <li><div class="signature"><span class="hardNobr">- (void)<a href="#NSString_RegexKitLiteAdditions__-flushCachedRegexData" class="selector">flushCachedRegexData</a>;</span></div></li>
	  <li><div class="signature"><span class="hardNobr">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/tdef/BOOL">BOOL</a>)<a href="#NSString_RegexKitLiteAdditions__-isRegexValid" class="selector">isRegexValid</a>;</span></div></li>
	</ul>

	<p>Deprecated Functionality:</p>
	<ul class="square">
	  <li>
	    <p><span class="signature"><span class="hardNobr">+ (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger">NSInteger</a>)<a href="#NSString_RegexKitLiteAdditions__.captureCountForRegex:" class="selector">captureCountForRegex:</a>(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span></span> <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</span></p>
	    <p>Use of <span class="code">captureCountForRegex:</span> is deprecated in favor of <a href="#NSString_RegexKitLiteAdditions__-captureCount" class="code">captureCount</a>.</p>
	  </li>
	  <li>
	    <p><span class="signature">- (<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSEnumerator_Class/Reference/Reference.html">NSEnumerator</a> *)matchEnumeratorWithRegex:(<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html">NSString</a> *)<span class="argument">regex</span>;</span> and <span class="code">RKLMatchEnumerator</span> <span class="deprecated">Deprecated in <span class="rkl">RegexKit<i>Lite</i></span> 3.0</span></p>
	    <p>The example code for <span class="code">RKLMatchEnumerator</span> available in <span class="file">examples/RKLMatchEnumerator.h</span> and <span class="file">examples/RKLMatchEnumerator.m</span> has been deprecated in favor of <a href="#NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:" class="code">componentsMatchedByRegex:</a>.</p>
	  </li>
	</ul>

	<p class="standout">Changes that effect the results that are returned:</p>

	<ul class="square">
	  <li>
	    <p>When the regular expression matched the tail end of the string to search, <a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">componentsSeparatedByRegex:</a> would incorrectly add a zero length string to the results returned.</p>

	    <div class="box sourcecode">NSArray *splitArray = [@&quot;Bob, Tom, Sam,&quot; componentsSeparatedByRegex:@&quot;,\\s*&quot;];

// <span class="comment">{ @&quot;Bob&quot;, @&quot;Tom&quot;, @&quot;Sam&quot;, @&quot;&quot; } &lt;- RegexKitLite &le; v2.2.</span>
// <span class="comment">{ @&quot;Bob&quot;, @&quot;Tom&quot;, @&quot;Sam&quot;      } &lt;- RegexKitLite &ge; v3.0.</span></div>
	  </li>

	  <li>
	    <p>The results returned by <a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">componentsSeparatedByRegex:</a> were found to differ from the expected results when zero-width assertions, such as <span class="regex">\b</span>, were used.  Prior to v3.0, regular expressions that matched zero characters would be considered a &#39;match&#39;, and a zero length string would be added to the results array.  The expected results are the results that are returned by the <span class="quotedText">perl</span> <span class="code">split()</span> function, which does not create a zero length string in such cases.  ICU ticket #<a href="http://bugs.icu-project.org/trac/ticket/6826" class="printURL">6826</a>.</p>

<div class="box sourcecode">NSArray *splitArray = [@&quot;I|at|ice I eat rice&quot; componentsSeparatedByRegex:@&quot;\\b\\s*&quot;];

// <span class="comment">ICU : { @&quot;&quot;, @&quot;I&quot;, @&quot;|&quot;, @&quot;at&quot;, @&quot;|&quot;, @&quot;ice&quot;, @&quot;&quot;, @&quot;I&quot;, @&quot;&quot;, @&quot;eat&quot;, @&quot;&quot;, @&quot;rice&quot; } &lt;- RegexKitLite &le; v2.2.</span>
// <span class="comment">perl: {      @&quot;I&quot;, @&quot;|&quot;, @&quot;at&quot;, @&quot;|&quot;, @&quot;ice&quot;,      @&quot;I&quot;,      @&quot;eat&quot;,      @&quot;rice&quot; } &lt;- RegexKitLite &ge; v3.0.</span></div>
	  </li>
	  <li>As part of the <span class="hardNobr">64-bit</span> tidy, a check of the length of a string that is passed to <span class="rkl">RegexKit<i>Lite</i></span>, and therefore ICU, was added to ensure that the length is less than <span class="code">INT_MAX</span>. If the length of the string <span class="hardNobr">is &ge; <span class="code">INT_MAX</span>,</span> then <span class="rkl">RegexKit<i>Lite</i></span> will raise <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Constants/Reference/reference.html#//apple_ref/doc/c_ref/NSRangeException" class="code">NSRangeException</a>.  The value of <span class="hardNobr"><span class="code">INT_MAX</span> is 2<sup>31</sup>-1 (<span class="code">0x7fffffff</span>).</span>  This was done because ICU uses the <span class="code">int</span> type for representing offset values.</li>
	</ul>

	<p>Other Changes:</p>
	<ul class="square">
	  <li>Ticket #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2027975&amp;group_id=204582&amp;atid=990188" class="printURL">2027975</a> - Request for <span class="code">captureCount</span> like functionality.</li>
	  <li>Ticket #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2779301&amp;group_id=204582&amp;atid=990191" class="printURL">2779301</a> - Request for <span class="code">componentsMatchedByRegex:</span> functionality.</li>
	  <li>Ticket #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2779965&amp;group_id=204582&amp;atid=990188" class="printURL">2779965</a> - Request that documentation be updated with how to match a literal <span class="consoleText">\</span> with a regex specified using a string literal: <span class="consoleText">@&quot;\\\\&quot;;</span>.</li>
	  <li>Ticket #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2786878&amp;group_id=204582&amp;atid=990191" class="printURL">2786878</a> - Request for <span class="code">isRegexValid</span> functionality.</li>
	  <li>The GCC variable <span class="code">cleanup</span> <span class="hardNobr code">__attribute__()</span> is now used to provide an extra safety net around the use of the <span class="rkl">RegexKit<i>Lite</i></span> spin lock.  The <span class="code">cleanup</span> function ensures that if the spin lock was locked by a function that it was also unlocked by the function.  If a function obtains the lock but does not unlock it, the <span class="code">cleanup</span> function forcibly unlocks the spin lock.</li>
	  <li>Minor GC changes.  Some minor changes in the way heap buffers were allocated was required to support the new methods that return a <span class="code">NSArray</span>.</li>
	  <li><span class="hardNobr">64-bit</span> cleanup.  Various literal numeric constant values had either <span class="code">L</span> or <span class="code">UL</span> appended to them if they were used with <span class="code">NSInteger</span>, <span class="code">NSUInteger</span>, or various other <span class="hardNobr">&#39;<span class="code">long</span>&#39;</span> data types.</li>
	  <li><span class="hardNobr">64-bit</span> cleanup.  Added checks to verify that a strings length is &lt; <span class="code">INT_MAX</span> and throw an exception if it isn&#39;t. This check was added because ICU uses signed <span class="hardNobr">32-bit</span> <span class="code">int</span> values to represent offsets.</li>
	  <li>Changed some macros to static inline functions for compile-time prototype checking.</li>
	  <li>Updated <span class="hardNobr file">examples/NSString-HexConversion.m</span>.  <span class="hardNobr">64-bit</span> tidies.</li>
	  <li>Updated <span class="hardNobr file">examples/RKLMatchEnumerator.h</span>.  Added the deprecated attribute to <span class="code">matchEnumeratorWithRegex:</span>.</li>
	  <li>Updated <span class="hardNobr file">examples/RKLMatchEnumerator.m</span>.  <span class="hardNobr">64-bit</span> tidies.  Added a preprocessor warning that <span class="code">RKLMatchEnumerator</span> has been deprecated in favor of <span class="code">componentsSeparatedByRegex:</span>.</li>
	  <li>Updated the documentations visual style to better match the style currently used by Apple.</li>
	  <li>Many small DocSet tweaks and improvements.</li>
	</ul>

	<p>Bug fixes:</p>
	<ul class="square">
	  <li>Bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2319200&amp;group_id=204582&amp;atid=990188" class="printURL">2319200</a> - The documentation for <span class="code">stringByReplacingOccurrencesOfRegex:withString:</span> (and related methods) was updated.  The text for the Returned Value section was obviously copy and pasted from somewhere else and never updated.  This has been fixed.</li>
	  <li>Bug #<a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=2408447&amp;group_id=204582&amp;atid=990188" class="printURL">2408447</a> - <span class="code">stringByReplacingOccurrencesOfRegex:</span> bug fixed. There was a bug in ICU that would cause a search and replace operation to fail with <span class="code">U_BUFFER_OVERFLOW_ERROR</span>, which would then cause <span class="rkl">RegexKit<i>Lite</i></span> to throw <a href="#RKLICURegexException" class="code">RKLICURegexException</a>, if the length of the replaced string was significantly longer than the original string.  ICU ticket #<a href="http://bugs.icu-project.org/trac/ticket/6656" class="printURL">6656</a></li>
	  <li><span class="code">componentsSeparatedByRegex:</span> bug fixed. When the regular expression matched the tail end of the string, an extra zero length string was incorrectly added to the results.</li>
	  <li><span class="code">componentsSeparatedByRegex:</span> bug fixed. The results returned by the ICU function <span class="hardNobr code">uregex_split()</span> was found to be different that the results returned by the <span class="quotedText">perl</span> <span class="hardNobr code">split()</span> function.  ICU ticket #<a href="http://bugs.icu-project.org/trac/ticket/6826" class="printURL">6826</a></li>
	  <li><span class="code">rangeOfRegex</span>, <span class="code">stringByMatching:</span> bug fixed. A bug was fixed where the <span class="code">inRange:</span> parameter was not correctly honored.</li>
	  <li>If <span class="rkl">RegexKit<i>Lite</i></span> was able to get direct access to a strings <span class="hardNobr code">UTF-16</span> buffer, there was a very remote chance that <span class="rkl">RegexKit<i>Lite</i></span> would continue to use a pointer to a strings older <span class="hardNobr code">UTF-16</span> buffer if the string mutated and allocated a new buffer.  The pointer to a strings direct buffer is now verified before each use.</li>
	  <li><span class="code">isMatchedByRegex:inRange:</span> was never documented.  Fixed.</li>
	</ul>
      </div>
    </div> <!-- release notes 3.0 -->

    <div class="entry" id="ReleaseInformation_31">
      <div class="banner"><span class="date">2009/05/15</span><span class="bannerItemSpacer">-</span><span class="release">3.1</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>This release of <span class="rkl">RegexKit<i>Lite</i></span> is a bug fix release.</p>

	<p>Bug Fixes:</p>
	<ul class="square">
	  <li>Bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2790480&amp;group_id=204582&amp;atid=990188" class="printURL">2790480</a> - If a regular expression had an error, as detected by ICU, then under some circumstances the <span class="code">lastCacheSlot</span> variable would not be properly cleared.  As a result, this would cause the pointer to the compiled regular expression to be <span class="code">NULL</span>.  The <span class="code">NULL</span> value would be caught by the run&#8209;time assertion checks if they were not disabled via <span class="cpp_flag">NS_BLOCK_ASSERTIONS</span>, otherwise it would most likely lead to a crash.</li>
	</ul>
      </div>
    </div> <!-- release notes 3.1 -->

    <div class="entry" id="ReleaseInformation_32">
      <div class="banner"><span class="date">2009/11/04</span><span class="bannerItemSpacer">-</span><span class="release">3.2</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>This release of <span class="rkl">RegexKit<i>Lite</i></span> is a bug fix release.</p>

	<p>Bug Fixes:</p>
	<ul class="square">
	  <li>Bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2828966&amp;group_id=204582&amp;atid=990188" class="printURL">2828966</a> - Fixed a minor bug that caused compiling on <span class="hardNobr">Mac OS X 10.4</span> to fail.  Changed the header include line from <span class="code hardNobr">#include &lt;objc/runtime.h&gt;</span>, which is available only on <span class="hardNobr">Mac OS X &ge; 10.5</span>, to <span class="code hardNobr">#include &lt;objc/objc-runtime.h&gt;</span>, which is available on <span class="hardNobr">Mac OS X &ge; 10.4</span>.</li>
	  <li>Bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2862398&amp;group_id=204582&amp;atid=990188" class="printURL">2862398</a> - Modified the logic for determining if the cached <span class="code hardNobr">UTF-16</span> conversion is valid for the string to be searched.  Previously, <span class="rkl">RegexKit<i>Lite</i></span> used a combination of the string to be searched <span class="code">hash</span> and <span class="code">length</span> to determine if the cached <span class="code hardNobr">UTF-16</span> conversion was a match.  For speed, <span class="code">NSString</span> only uses a fixed number of characters to calculate the hash.  This means that as the length of a string grows, the hash function becomes less effective at detecting differences between strings.  The original intent behind the <span class="code hardNobr">UTF-16</span> conversion cache logic was to be able to re-use the <span class="code hardNobr">UTF-16</span> conversion for strings that were <span class="hardNobr">&quot;the same&quot;</span> <span class="hardNobr">(i.e., hash equality),</span> but were different instantiations <span class="hardNobr">(i.e., pointer inequality).</span>  On reflection, it was decided that the more likely real-world case would be strings that would share the same hash value, but actually be slightly different.  <span class="rkl">RegexKit<i>Lite</i></span> now requires that the <span class="code">NSString</span> pointer, as well as the <span class="code">hash</span> and <span class="code">length</span>, be the same as the string used for the cached <span class="code hardNobr">UTF-16</span> conversion.</li>
	  <li>Bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2879356&amp;group_id=204582&amp;atid=990188" class="printURL">2879356</a> - <span class="code">arrayOfCaptureComponentsMatchedByRegex:</span>, <span class="code">captureComponentsMatchedByRegex:</span>, <span class="code">componentsMatchedByRegex:</span>, and <span class="code">componentsSeparatedByRegex:</span> bug fixed.  Originally reported by Jesse Grosjean. Duplicate bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2890342&amp;group_id=204582&amp;atid=990188" class="printURL">2890342</a>.  If a regex matched a part of the string that included the very end of the string, subsequent matches would incorrectly return that the regex did not match the string.  Clearing the cache, either manually or because another regex match replaced the affected cache slot, would clear the condition.</li>
	  <li>Bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;atid=990188&amp;aid=2890810&amp;group_id=204582" class="printURL">2890810</a> - <span class="code">stringByReplacingOccurrencesOfRegex:</span> bug fixed.  If the size of the buffer needed to hold the replaced string was larger than the initial estimated buffer size, ICU should return an error of <span class="code">U_BUFFER_OVERFLOW_ERROR</span>.  However, due to a bug in ICU (see bug #<a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=2408447&amp;group_id=204582&amp;atid=990188" class="printURL">2408447</a>, ICU ticket #<a href="http://bugs.icu-project.org/trac/ticket/6656" class="printURL">6656</a>), this error was not reported correctly and a workaround was implemented.  A rare corner case could cause ICU to return <span class="code">U_STRING_NOT_TERMINATED_WARNING</span> during the time that <span class="rkl">RegexKit<i>Lite</i></span> was calculating the size of the buffer needed to hold all of the replaced string.  When this happened it would cause <span class="rkl">RegexKit<i>Lite</i></span> to miss the <span class="code">U_BUFFER_OVERFLOW_ERROR</span> error needed to resize the buffer.</li>
	</ul>
      </div>
    </div> <!-- release notes 3.2 -->

    <div class="entry" id="ReleaseInformation_33">
      <div class="banner"><span class="date">2009/11/07</span><span class="bannerItemSpacer">-</span><span class="release">3.3</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>This release of <span class="rkl">RegexKit<i>Lite</i></span> is a bug fix release.</p>

	<p>Bug Fixes:</p>
	<ul class="square">
	  <li>Bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;atid=990188&amp;aid=2893824&amp;group_id=204582" class="printURL">2893824</a> - Fixed a minor bug that caused compiling with the iPhone device SDK to fail.  This is related to the <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 3.2</span> fix for bug #<a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2828966&amp;group_id=204582&amp;atid=990188" class="printURL">2828966</a>.  It turns out that the iPhone simulator SDK has the header file <span class="file">objc/objc-runtime.h</span>, but the iPhone device SDK only has the header file <span class="file">objc/runtime.h</span>.  <span class="rkl">RegexKit<i>Lite</i></span> will now conditionally use <span class="code hardNobr">#include &lt;objc/runtime.h&gt;</span> when targeting the iPhone or <span class="hardNobr">Mac OS X &ge; 10.5</span>, and <span class="code hardNobr">#include &lt;objc/objc-runtime.h&gt;</span> when targeting <span class="hardNobr">Mac OS X &le; 10.4</span>.</li>
	</ul>
      </div>
    </div> <!-- release notes 3.3 -->


    <div class="entry" id="ReleaseInformation_40">
      <div class="banner"><span class="date">2010/04/18</span><span class="bannerItemSpacer">-</span><span class="release">4.0</span></div>
      <div class="bannerSpacer"></div>
      <div class="content">
	
	<p>This release of <span class="rkl">RegexKit<i>Lite</i></span> is a major release that includes new features, new APIs, and bug fixes.</p>
	
	<p class="standout">API Compatibility Changes:</p>

	<ul class="square">

	  <li>
	    <p>The <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSMutableString_Class/index.html" class="code">NSMutableString</a> <span class="hardNobr"><span class="code">replaceOccurrencesOfRegex:</span>&hellip;</span> methods now return a result of type <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSInteger" class="code">NSInteger</a>, whereas <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> &lt; 4.0</span> returned a result of type <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_DataTypes/Reference/reference.html#//apple_ref/c/tdef/NSUInteger" class="code">NSUInteger</a>. This change, while technically breaking API compatibility, is likely to be completely backwards compatible for most users. The change was made so that errors, such as an invalid regular expression, can be distinguished from a search and replace operation that replaced zero occurrences. An error condition that is not an exception now returns a value of <span class="code">-1</span>. Prior to <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 4.0,</span> the only way to distinguish between a search and replace operation that replaced zero occurrences and an error that prevented a search and replace from taking place was to use a <span class="hardNobr"><span class="code">replaceOccurrencesOfRegex:</span>&hellip;</span> method with an <span class="code">error:</span> parameter.</p>
	  </li>
	</ul>

	<p class="standout">Changes that effect the results that are returned:</p>

	<ul class="square">
	  <li>
	    <p>The results returned by <a href="#NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:" class="code">componentsSeparatedByRegex:</a> were found to differ from the expected results for some regex patterns. For example, prior to v4.0, when the regular expression <span class="regex">.</span> (dot, match any character) was used to split a string, <span class="rkl">RegexKit<i>Lite</i></span> returned an array of seven zero length strings.  The expected results are the results that are returned by the <span class="quotedText">perl</span> <span class="code">split()</span> function&ndash; the equivalent of a <span class="code">NSArray</span> with zero items in it.</p>

	    <div class="box sourcecode">NSArray *splitArray = [@&quot;abc.def&quot; componentsSeparatedByRegex:@&quot;.&quot;];

// <span class="comment">{ @&quot;&quot;, @&quot;&quot;, @&quot;&quot;, @&quot;&quot;, @&quot;&quot;, @&quot;&quot;, @&quot;&quot; } &lt;- RegexKitLite &le; v3.3.</span>
// <span class="comment">{                                   } &lt;- RegexKitLite &ge; v4.0 &amp; perl.</span></div>
	  </li>
	</ul>

	<p>New features:</p>

	<ul class="square">
	  <li>
	    <p>Documentation now available in PDF format.</p>

	    <p>The <span class="rkl">RegexKit<i>Lite</i></span> documentation is now available in PDF format.  The PDF version is ideal for making printed copies of the documentation.</p>

	  </li>
	  <li>
	    <p>Improved compiled regular expression cache.</p>

	    <p><span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> versions &lt; 4.0</span> used a direct mapped, or 1-way set associative, cache.  <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 4.0</span> uses a 4-way set associative cache.  In general, a <span class="hardNobr"><i>n</i>-way</span> set associative cache, where <span class="hardNobr"><i>n</i> &gt; <span class="code">1</span>,</span> has fewer misses than a direct mapped cache.  Entries in a set are managed on a least recently used, or LRU, basis.  This means that when a compiled regular expression is added to the cache, the entry in a set that is the least recently used is the one chosen to hold the new compiled regular expression.</p>

	    <p>In benchmark tests, the old compiled regular expression cache required a <b><i>dramatically</i></b> larger cache size to achieve the same effectiveness <span class="hardNobr">(i.e.,</span> the likelihood that the regular expression was already in the cache) as the new compiled regular expression cache. Retrieving a cached compiled regular expression is <b><i>541.3</i></b> times faster<sup>&dagger;</sup> than actually compiling the regular expression:</p>

	    <div style="margin-left: 2ex; margin-top: 1em;">
	      <table class="standard">
		<tr><th>Retrieve</th><th>Time</th><th>Rate (per second)</th></tr>
		<tr><td><b>Cached</b></td><td align="right"><span class="hardNobr">51 ns</span></td><td align="right">19,680,762</td></tr>
		<tr><td><b>Compile</b></td><td align="right"><span class="hardNobr">27,560 ns</span></td><td align="right">36,285</td></tr>
	      </table>
	      <p><sup>&dagger;</sup>Timing done a <span class="hardNobr">MacBook Pro 2.66GHz</span> running <span class="hardNobr">Mac OS X 10.6.2.</span></p>
	    </div>
	  </li>

	  <li>
	    <p>Improved <span class="code">UTF-16</span> conversion cache.</p>

	    <p>The <span class="code">UTF-16</span> conversion cache now uses the same 4-way set associative cache system as the compiled regular expression cache.  For strings that required a <span class="code">UTF-16</span> conversion, <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> versions &lt; 4.0</span> used two buffers for caching <span class="code">UTF-16</span> conversions&mdash; a small, fixed sized buffer for &#39;small&#39; strings <span class="hardNobr">(&le; <span class="code">2048</span></span> characters by default), and a dynamically sized buffer for &#39;large&#39; strings.  <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 4.0</span> keeps the same fixed and dynamic size dichotomy, but now each type contains four buffers which are reused on a least recently used basis.</p>
	  </li>
	  <li>
	    <p>Blocks support.</p>
	    
	    <p>Although support for blocks was introduced with <span class="hardNobr">Mac OS X 10.6</span>, you can still use blocks on <span class="hardNobr">Mac OS X 10.5</span> and <span class="hardNobr">iPhone &ge; 2.2</span> by using <a href="http://code.google.com/p/plblocks/" class="printURL">Plausible Blocks</a>.  This solution provides a compiler and runtime that has been back-ported from the <span class="hardNobr">Mac OS X 10.6</span> <span class="hardNobr">Snow Leopard</span> sources.</p>
	    
	    <div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
<span class="rkl">RegexKit<i>Lite</i></span> checks if the C preprocessor define <span class="cpp_flag">NS_BLOCKS_AVAILABLE</span> is set to <span class="code">1</span> to automatically determine if blocks functionality should be enabled.  Typically <span class="cpp_flag">NS_BLOCKS_AVAILABLE</span> is only set to <span class="code">1</span> when using the standard developer tools and the minimum version of <span class="hardNobr">Mac OS X</span> supported is set to <span class="hardNobr">10.6</span>.  <span class="rkl">RegexKit<i>Lite</i></span> blocks support can be explicitly enabled by setting <span class="cpp_flag">RKL_BLOCKS</span> to <span class="code">1</span> <span class="hardNobr">(i.e.,</span> <span class="consoleText">-DRKL_BLOCKS=1</span>).  The behavior is undefined if <span class="cpp_flag">RKL_BLOCKS</span> is set to <span class="code">1</span> and the compiler does not support the blocks language extension or if the run-time does not support blocks.
	    </div></div></div></div>

	    <div class="section seealso" style="margin-top: 0.75em"><div class="header">See Also</div>
	      <ul class="offset">
		<li><a href="http://code.google.com/p/plblocks/" class="section-link printURL">Plausible Blocks - PLBlocks</a></li>
	      </ul>
	    </div>

	  </li>
	</ul>

	<p>New <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/index.html" class="code">NSString</a> Methods:</p>

	<ul class="square">
	  <li><a href="#NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:" class="code">- dictionaryByMatchingRegex:withKeysAndCaptures:</a></li>
	  <li><a href="#NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:" class="code">- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:</a></li>
	</ul>

	<p>New Block-based <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/index.html" class="code">NSString</a> Methods:</p>

	<ul class="square">
	  <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:" class="code">- enumerateStringsMatchedByRegex:usingBlock:</a></li>
	  <li><a href="#NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:" class="code">- enumerateStringsSeparatedByRegex:usingBlock:</a>
	  <li><a href="#NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:" class="code">- stringByReplacingOccurrencesOfRegex:usingBlock:</a></li>
	</ul>
	
	<p>New Block-based <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSMutableString_Class/index.html" class="code">NSMutableString</a> Methods:</p>
	
	<ul class="square">
	  <li><a href="#NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:" class="code">- replaceOccurrencesOfRegex:usingBlock:</a></li>
	</ul>

	<p>Other changes:</p>
	
	<ul class="square">
	  <li>Improved performance.  Many small performance tweaks and optimizations were made to frequently used code paths.</li>
	  <li>The meaning of <span class="cpp_flag">RKL_CACHE_SIZE</span> changed.  This compile-time preprocessor tunable now controls the number of &quot;sets&quot; in the compiled regular expression cache, and each &quot;set&quot; contains four entries.  This means that the maximum number of potential compiled regular expressions that can be cached is <span class="cpp_flag">RKL_CACHE_SIZE</span> times four.  Like previous versions, <span class="cpp_flag">RKL_CACHE_SIZE</span> should always be a prime number to maximize the use of the cache.</li>
	  <li><span class="cpp_flag">RKL_CACHE_SIZE</span> changed to <span class="code">13</span>.  The total number of compiled regular expressions that can be cached is <span class="code hardNobr">13 * 4</span>, or <span class="code">52</span>.  This is a 126% increase from previous versions of <span class="rkl">RegexKit<i>Lite</i></span> which had a default value of <span class="code">23</span> for <span class="cpp_flag">RKL_CACHE_SIZE</span>.</li>
	  <li>Added the flag <a href="#dtrace_utf16ConversionCache_lookupResultFlags_RKLEnumerationBufferLookupFlag" class="code">RKLEnumerationBufferLookupFlag</a> to the DTrace <a href="#dtrace_utf16ConversionCache_lookupResultFlags" class="code">RegexKitLite:::utf16ConversionCache</a> flags.</li>
	  <li>Added a number of new keys to <a href="#RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys" class="section-link"><span class="rkl">RegexKit<i>Lite</i></span> NSError and NSException User Info Dictionary Keys</a>.</li>
	</ul>

	<p>Bug fixes:</p>

	<ul class="square">
	  <li>If the ICU library returned a status of <span class="code">U_STRING_NOT_TERMINATED_WARNING</span> during a search and replace operation, <span class="rkl">RegexKit<i>Lite</i></span> erred on the side of caution and treated it as a failure due to the numerous search and replace bugs in the past.  <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 4.0</span> continues to err on the side of caution, but now treats <span class="code">U_STRING_NOT_TERMINATED_WARNING</span> as if the ICU library had returned a status of <span class="code">U_BUFFER_OVERFLOW_ERROR</span>.</li>
	  <li>The <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSMutableString_Class/index.html" class="code">NSMutableString</a> <span class="hardNobr"><span class="code">replaceOccurrencesOfRegex:</span>&hellip;</span> methods could have returned a value <span class="hardNobr">&gt; <span class="code">0</span>,</span> the replaced count, even if no actual replacements were performed.  This would occur if an error was encountered during the search and replace, in which case the replaced count was not correctly reset to <span class="code">0</span>.  <span class="hardNobr"><span class="rkl">RegexKit<i>Lite</i></span> 4.0</span> changed the <span class="hardNobr"><span class="code">replaceOccurrencesOfRegex:</span>&hellip;</span> API so that a value of <span class="code">-1</span> could be returned to indicate that an error was encountered.</li>
	  <li><span class="code">componentsSeparatedByRegex:</span> bug fixed. The results returned were found to be different that the results returned by the <span class="consoleText">perl</span> <span class="code">split()</span> function.</li>

	</ul>
      </div>
    </div> <!-- release notes 4.0 -->

    
  </div>
</div>

<div class="printPageBreakAfter">
  <h2 id="Epilogue">Epilogue</h2>

  <h3>Coding Style</h3>

  <p>One noticeable break in style conventions is in line lengths. There was a time when 80 column limits made a lot of sense as it was the lowest common denominator. Today, a modern computer screen can display much more than just 80 columns.  Even an iPhone, which has a screen size of <span class="hardNobr">320x480,</span> can display 96 columns by 24 rows of the usual <span class="hardNobr">Terminal.app</span> Monaco 10pt font (5x13 pixels) in landscape mode.  Because of this, my personal style is not to have an arbitrary limit on line lengths. This allows for much more code to fit on the screen at once, which I&#39;ve heard referred to as &quot;Man&mdash;Machine Interface Bandwidth&quot;. While you can always page up and down, the simple movement of your eye is almost always an order of magnitude faster. Paging through code also tends to break your concentration as you briefly try to mentally orientate yourself with the freshly displayed text and where the section of code is that you&#39;re looking for.</p>

  <p>I try to group a line around relevancy so that based on the start of the line you can quickly determine if the rest of the line is applicable. Clearly the number of spaces used to indent a block plays a similar role, it allows you to quickly visually establish the logical boundaries of what lines of code are applicable. I also try to horizontally align related statements since your eye tends to be extremely sensitive to such visual patterns. For example, in variable declaration and initialization, I try to align the type declaration and the <span class="code">=</span> (equal sign) across multiple lines. This tends to cause the declaration type, the variable name, and the value assigned to visually <i>pop</i>. Without the alignment, you typically have to scan back and forth along a line to separate and find a variable name and its initialization value. Sometimes line breaks and horizontal alignment are done purely on what&#39;s subjectively aesthetically pleasing and allows the eye to quickly <i>flow</i> over the code.</p>

  <p>The source code of <span class="rkl">RegexKit<i>Lite</i></span> isn&#39;t exactly what you&#39;d call clean, there&#39;s more than a few crufty <b>C</b> barnacles in there.  There is usually a choice between two polar opposites and in this case it&#39;s between elegant, easy to maintain and comprehend code, and speed.  If you use regular expressions for very long, you will undoubtedly encounter a situation where you need to scan through tens of megabytes of text and the speed of your regular expression matching loop needs to be faster.  <b><i>A lot faster.</i></b>  <span class="rkl">RegexKit<i>Lite</i></span> was written to go fast, and the source code style reflects this choice.</p>

  <h4>The Need for Speed</h4>

  <p>A significant amount of time was spent using Shark to optimize the critical sections of <span class="rkl">RegexKit<i>Lite</i></span>.  This included tweaking even the most insignificant details, such as the order of boolean expressions in <span class="code">if()</span> statements to minimize the number of branches that would have to be evaluated to determine if the statement is true or false. Wherever possible, <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> is used directly. This avoids the overhead of an <span class="hardNobr">Objective-C</span> message dispatch, which would invariably end up calling the exact same <a href="http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation_Collection/index.html" class="section-link hardNobr">Core Foundation</a> function anyways.</p>

  <p>Even the cache has what is essentially a cache&mdash; the last regular expression used.  Each time a regular expression is used, the compiled ICU regular expression must be retrieved from the cache, or if it does not exist in the cache, instantiated.  Checking the cache involves calculating the remainder of the regular expression strings hash modulo the cache size prime, which is a moderately expensive division and multiplication operation.  However, checking if the regular expression being retrieved this time is exactly the same as the last regular expression retrieved is just a fast and simple comparison check.  As it turns out, this is very often the case.  Even the functions are arranged in such a way that the compiler will often inline everything in to one large aggregate function, eliminating the overhead of a function call in many places.</p>

  <p>Normally, this kind of micro-optimization is completely unjustified. A rough rule of thumb is that 80% of your programs execution time is spent in 20% of your programs code.  The only code worth optimizing is the 20% that is heavily executed. If your program makes heavy use of regular expressions, such as a loop that scans megabytes of text using regular expressions, <span class="rkl">RegexKit<i>Lite</i></span> is almost guaranteed to be a part of the 20% of code where most of the execution time is spent.  The release notes for <a href="http://osx.iusethis.com/app/versions/coteditor">CotEditor</a> would seem to indicate that all this effort has paid off for at least one user:</p>

  <div class="box quote">
    <p style="margin-bottom: 1em;" class="quotedText">More than 10.4 when running on the color process to review the details of the definition of a regular expression search RegexKitLite adopted, 0.9.3, as compared to the speed of color from 1.5 to 4 times as much improved.</p>

    <div class="box note"><div class="table"><div class="row"><div class="label cell">Note:</div><div class="message cell">
	    <p>This is an automatic machine translation from Japanese to English.</p>
    </div></div></div></div>
  </div>

  <h3>Documentation</h3>

  <p>Clearly documentation has been a high priority for this project.  Documentation is always hard to write and good documentation is exponentially harder still.  The vast majority of &#39;development effort and time&#39; is spent on the documentation.  It&#39;s always hard to judge the quality and effectiveness of something you wrote, so hopefully the extra effort is worth it and appreciated.</p>

<p>As an aside and a small rant, I have no idea how anyone manages to build so-called &#39;web applications&#39;.  I waste a truly unbelievable amount of time trying to accomplish the simplest of things in HTML, which is then multiplied when I check for &#39;compatibility&#39; with different browsers and their various popular versions.  What a joke, and that&#39;s just for this &#39;simple&#39; documentation.  Though I do have to give kudos to the Safari / WebKit guys, it always seems to be a lot easier to get the result you&#39;re looking for with the WebKit engine.  The little things add so much: shadows, round rects, gradients, CSS animations, the canvas element, etc.</p>

  <h3>Questions about licensing, including in your software, etc</h3>

  <div class="faq">
    <div class="qa">
      <div class="q">What do I need to do to include <span class="rkl">RegexKit<i>Lite</i></span> in my software?</div>
      <div class="a">Not much.  The <i class="hardNobr">BSD License</i> is very permissive.  In short, you just need to &#39;acknowledge&#39; your use of it.  Safari&#39;s <span class="context-menu hardNobr">Help </span><span class="submenuArrow">&#9658;</span><span class="context-menu"> Acknowledgements</span> is a good example of this.</div>
    </div>

    <div class="qa">
      <div class="q">I am selling a &#39;closed-source&#39; commercial application.  I would like to use <span class="rkl">RegexKit<i>Lite</i></span> in it, how much will it cost?</div>
      <div class="a"><span class="rkl">RegexKit<i>Lite</i></span> is free for any use.</div>
    </div>

    <div class="qa">
      <div class="q">Do I have to distribute the source with my application?</div>
      <div class="a">No.  Unlike the <a href="http://www.gnu.org/licenses/licenses.html" class="section-link printURL">GNU GPL License</a>, there is no requirement that you include or make the source code available, even if you release a &quot;compiled, binaries only&quot; end product.</div>
    </div>

    <div class="qa">
      <div class="q">What about modifications to <span class="rkl">RegexKit<i>Lite</i></span>?  Do I have to make any changes that I make available?  Or contribute them back to the author of <span class="rkl">RegexKit<i>Lite</i></span>?</div>
      <div class="a">You may make any modifications you want and are under no obligation to release those changes to anyone.</div>
    </div>

    <div class="qa">
      <div class="q">Why the <i class="hardNobr">BSD License</i>?</div>
      <div class="a"><p>It&#39;s a well known license.  If you are part of a Large Corporate Organization, chances are the Corporate Lawyers have Decided whether or not the use of source code licensed under the <i class="hardNobr">BSD License</i> is Acceptable or not.  This can be a godsend for anyone who has to deal with such situations.</p>
	<p>It also expresses a few things I think are perfectly reasonable:</p>
	<ol>
	  <li>Give credit where credit is due.</li>
	  <li>There is no warranty, so use it at your own risk.</li>
	  <li>You can&#39;t hold the author responsible.</li>
	</ol>
	<p>The first point is prescribed by most professional ethics already.  Plus, it&#39;s always nice to see where your stuff ends up and how it&#39;s being used.  The other points make explicit what should already be obvious.  After all, you get what you pay for.</p>
      </div>
    </div>
  </div>

</div>

<div>
  <h2 id="LicenseInformation">License Information</h2>
  
  <p><span class="rkl">RegexKit<i>Lite</i></span> is distributed under the terms of the <i class="hardNobr">BSD License</i>, as specified below.</p>
  
  <div class="section seealso"><div class="header">See Also</div>
    <ul class="offset">
      <li><a href="http://en.wikipedia.org/wiki/BSD_license" class="section-link printURL">Wikipedia - BSD License</a></li>
      <li><a href="http://www.linfo.org/bsdlicense.html" class="section-link printURL">The Linux Information Project - BSD License Definition</a></li>
    </ul>
  </div>
  
  
  <h3>License</h3>
  
  <div class="sourceLicense"><p>Copyright &copy; 2008-2010, John Engelhart</p>
    
    <p>All rights reserved.</p>

    <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
    
    <ul>
      <li>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</li>
      <li>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</li>
      <li>Neither the name of the Zang Industries nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.</li>
    </ul>
    
    <p class="disclaimer">THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS &quot;AS IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
  </div>
</div>


<div class="screenOnly">
  <!-- Used by javascript from various shiny chrome bits. -->
  <div class="screenOnly" style="display: none;" id="pulseOutline">&nbsp;</div>
  <div class="screenOnly copyToClipboardHUD" style="display: none;" id="copyToClipboardHUD">
    <div class="top" id="copyToClipboardHUDTop">
      <div class="padding">
	<div class="copiedAs">Copied to Clipboard as:</div>
	<div class="regex copyToClipboardHUDRegex" id="copyToClipboardHUDRegex">&hellip;</div>
      </div>
    </div>
  </div>
</div>


</body>
</html>
